@woosh/meep-engine 2.131.14 → 2.131.17

package/README.md

@@ -14,13 +14,13 @@ To help get you started, various samples are provided under `/samples` folder. F
 ## Quality
 
 ### Testing
-Meep is covered by 2,801 handwritten unit tests, reaching 90%+ coverage in `core` and 40%+ coverage total.
+Meep is covered by 2,944 handwritten unit tests, reaching 90%+ coverage in `core` and 40%+ coverage total.
 
 The aim is to [ensure quality](https://about.codecov.io/blog/the-case-against-100-code-coverage/). As a result, the tests are written to cover complex code first and to exhaustively validate critical algorithms.
 Most of the test code is significantly larger than the code that is being tested.
 
 ### Assertions
-Meep is covered by 3,162 asserts. [Assertions](https://en.wikipedia.org/wiki/Assertion_(software_development)) provide very extensive pre- and post-condition checks throughout the engine.
+Meep is covered by 3,968 asserts. [Assertions](https://en.wikipedia.org/wiki/Assertion_(software_development)) provide very extensive pre- and post-condition checks throughout the engine.
 Asserts are intended primarily for development builds.
 To remove asserts in Vite builds, you can use `@rollup/plugin-strip` package like so:
 

package/package.json

@@ -5,7 +5,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.131.14",
+  "version": "2.131.17",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/codegen/LineBuilder.d.ts

@@ -1,6 +1,7 @@
 export default LineBuilder;
 /**
  * Useful for generating formatted snippets of code.
+ *
  * @example
  *  const b = new LineBuilder();
  *  b.add("function hello(){");
@@ -38,9 +39,10 @@ declare class LineBuilder {
      */
     get count(): number;
     /**
-     * Substring test of per-line basis. A match can only span a single line, so multi-line matches will not be found.
-     * @return {boolean}
+     * Substring test on a per-line basis.
+     * A match can only span a single line, so multi-line matches will not be found.
      * @param {string} term
+     * @return {boolean} true if the term was found at least once, false otherwise
      */
     containsSubstring(term: string): boolean;
     /**

package/src/core/codegen/LineBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LineBuilder.d.ts","sourceRoot":"","sources":["../../../../src/core/codegen/LineBuilder.js"],"names":[],"mappings":";AAgCA;;;;;;;;;;;;;GAaG;AACH;IAkLI;;;;OAIG;IACH,sBAJW,MAAM,mBACN,MAAM,GACJ,WAAW,CAuBvB;IA9LD;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,qBAAqC;IAErC;;;OAGG;IACH,oBAEC;IAED;;;;OAIG;IACH,wBAFW,MAAM,GADL,OAAO,CAoBlB;IAED;;;OAGG;IACH,UAFa,WAAW,CAKvB;IAED;;;OAGG;IACH,UAFa,WAAW,CAQvB;IAED;;;;;OAKG;IACH,eAHW,MAAM,GACJ,WAAW,CASvB;IAED;;;;;;;;;;;OAWG;IACH,aATW,MAAM,GACJ,IAAI,CAmBhB;IAED;;;OAGG;IACH,gBAFW,WAAW,QAiBrB;IAED,cAGC;IAED;;;OAGG;IACH,SAFa,MAAM,CAyBlB;IA8BD,mBAEC;;CACJ"}
+{"version":3,"file":"LineBuilder.d.ts","sourceRoot":"","sources":["../../../../src/core/codegen/LineBuilder.js"],"names":[],"mappings":";AAgCA;;;;;;;;;;;;;;GAcG;AACH;IAoLI;;;;OAIG;IACH,sBAJW,MAAM,mBACN,MAAM,GACJ,WAAW,CAuBvB;IAhMD;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,qBAAqC;IAErC;;;OAGG;IACH,oBAEC;IAED;;;;;OAKG;IACH,wBAHW,MAAM,GACL,OAAO,CAoBlB;IAED;;;OAGG;IACH,UAFa,WAAW,CAKvB;IAED;;;OAGG;IACH,UAFa,WAAW,CAQvB;IAED;;;;;OAKG;IACH,eAHW,MAAM,GACJ,WAAW,CASvB;IAED;;;;;;;;;;;OAWG;IACH,aATW,MAAM,GACJ,IAAI,CAmBhB;IAED;;;OAGG;IACH,gBAFW,WAAW,QAiBrB;IAED,cAGC;IAED;;;OAGG;IACH,SAFa,MAAM,CAyBlB;IA8BD,mBAEC;;CACJ"}

package/src/core/codegen/LineBuilder.js

@@ -32,6 +32,7 @@ const DEFAULT_INDENT_SPACES = 4;
 
 /**
  * Useful for generating formatted snippets of code.
+ *
  * @example
  *  const b = new LineBuilder();
  *  b.add("function hello(){");
@@ -83,9 +84,10 @@ class LineBuilder {
     }
 
     /**
-     * Substring test of per-line basis. A match can only span a single line, so multi-line matches will not be found.
-     * @return {boolean}
+     * Substring test on a per-line basis.
+     * A match can only span a single line, so multi-line matches will not be found.
      * @param {string} term
+     * @return {boolean} true if the term was found at least once, false otherwise
      */
     containsSubstring(term) {
         assert.isString(term, 'term');
@@ -99,6 +101,7 @@ class LineBuilder {
             const termIndex = line.text.indexOf(term);
 
             if (termIndex !== -1) {
+                // match
                 return true;
             }
         }

package/src/core/color/YCbCr/YCbCr_to_rgb_uint24.d.ts

@@ -1,9 +1,10 @@
 /**
- * @see https://en.wikipedia.org/wiki/YUV
- * @param {number} Y in range 0...255
- * @param {number} Cb in range 0...255
- * @param {number} Cr in range 0...255
- * @returns {number}
+ * Converts YCbCr (Rec. 709) to RGB.
+ *
+ * @param {number} Y Luma (0-255)
+ * @param {number} Cb Blue Difference (0-255)
+ * @param {number} Cr Red Difference (0-255)
+ * @returns {number} packed 24-bit integer: 0xRRGGBB
  */
 export function YCbCr_to_rgb_uint24(Y: number, Cb: number, Cr: number): number;
 //# sourceMappingURL=YCbCr_to_rgb_uint24.d.ts.map

package/src/core/color/YCbCr/YCbCr_to_rgb_uint24.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"YCbCr_to_rgb_uint24.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/YCbCr/YCbCr_to_rgb_uint24.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,uCALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAalB"}
+{"version":3,"file":"YCbCr_to_rgb_uint24.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/YCbCr/YCbCr_to_rgb_uint24.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,uCALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAgBlB"}

package/src/core/color/YCbCr/YCbCr_to_rgb_uint24.js

@@ -1,19 +1,25 @@
+import { clamp } from "../../math/clamp.js";
+
 /**
- * @see https://en.wikipedia.org/wiki/YUV
- * @param {number} Y in range 0...255
- * @param {number} Cb in range 0...255
- * @param {number} Cr in range 0...255
- * @returns {number}
+ * Converts YCbCr (Rec. 709) to RGB.
+ *
+ * @param {number} Y Luma (0-255)
+ * @param {number} Cb Blue Difference (0-255)
+ * @param {number} Cr Red Difference (0-255)
+ * @returns {number} packed 24-bit integer: 0xRRGGBB
  */
 export function YCbCr_to_rgb_uint24(Y, Cb, Cr) {
-    const _Cr = Cr - 128;
-    const _Cb = Cb - 128;
+    const C_red = Cr - 128;
+    const C_blue = Cb - 128;
+
+    // Rec. 709 Inverse Coefficients
+    // R = Y + 1.5748 * Cr
+    // G = Y - 0.1873 * Cb - 0.4681 * Cr
+    // B = Y + 1.8556 * Cb
 
-    const r = Y + _Cr + (_Cr >> 2) + (_Cr >> 3) + (_Cr >> 5);
-    const g = Y - ((_Cb >> 2) + (_Cb >> 4) + (_Cb >> 5)) - ((_Cr >> 1) + (_Cr >> 3) + (_Cr >> 4) + (_Cr >> 5));
-    const b = Y + _Cb + (_Cb >> 1) + (_Cb >> 2) + (_Cb >> 6);
+    const r = clamp(Math.round(Y + 1.5748 * C_red), 0, 255);
+    const g = clamp(Math.round(Y - 0.1873 * C_blue - 0.4681 * C_red), 0, 255);
+    const b = clamp(Math.round(Y + 1.8556 * C_blue), 0, 255);
 
-    return ((r << 16) & 0xFF0000)
-        | ((g << 8) & 0xFF00)
-        | (b & 0xFF);
+    return ((r << 16) | (g << 8) | b) >>> 0;
 }

package/src/core/color/YCbCr/rgb_to_YCbCr_uint24.d.ts

@@ -1,9 +1,10 @@
 /**
+ * Converts RGB to YCbCr (Rec. 709 / HDTV Full Range).
  *
- * @param r in range 0...255
- * @param g in range 0...255
- * @param b in range 0...255
- * @return {number}
+ * @param {number} r Red (0-255)
+ * @param {number} g Green (0-255)
+ * @param {number} b Blue (0-255)
+ * @return {number} packed 24-bit integer: 0xYYCbCr
  */
-export function rgb_to_YCbCr_uint24(r: any, g: any, b: any): number;
+export function rgb_to_YCbCr_uint24(r: number, g: number, b: number): number;
 //# sourceMappingURL=rgb_to_YCbCr_uint24.d.ts.map

package/src/core/color/YCbCr/rgb_to_YCbCr_uint24.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb_to_YCbCr_uint24.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/YCbCr/rgb_to_YCbCr_uint24.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,6DAFY,MAAM,CAUjB"}
+{"version":3,"file":"rgb_to_YCbCr_uint24.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/YCbCr/rgb_to_YCbCr_uint24.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,uCALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAcjB"}

package/src/core/color/YCbCr/rgb_to_YCbCr_uint24.js

@@ -1,16 +1,24 @@
+import { clamp } from "../../math/clamp.js";
+import { rgb_to_luminance } from "../rgb_to_luminance.js";
+
 /**
+ * Converts RGB to YCbCr (Rec. 709 / HDTV Full Range).
  *
- * @param r in range 0...255
- * @param g in range 0...255
- * @param b in range 0...255
- * @return {number}
+ * @param {number} r Red (0-255)
+ * @param {number} g Green (0-255)
+ * @param {number} b Blue (0-255)
+ * @return {number} packed 24-bit integer: 0xYYCbCr
  */
 export function rgb_to_YCbCr_uint24(r, g, b) {
-    const Y = 0.299 * r + 0.587 * g + 0.114 * b;
-    const Cb = -0.169 * r - 0.331 * g + 0.499 * b + 128;
-    const Cr = 0.499 * g - 0.418 * g - 0.0813 * b + 128;
+    const Y = clamp(Math.round(rgb_to_luminance(r,g,b)), 0, 255);
+
+    // Rec. 709 Chroma Coefficients
+    // Derived from: 0.5 / (1 - Kb) and 0.5 / (1 - Kr)
+
+    const Cb = clamp(Math.round(-0.1146 * r - 0.3854 * g + 0.5000 * b + 128), 0, 255);
+    const Cr = clamp(Math.round(0.5000 * r - 0.4542 * g - 0.0458 * b + 128), 0, 255);
 
-    return ((Y << 16) & 0xFF0000)
-        | ((Cb << 8) & 0xFF00)
-        | (Cr & 0xFF);
+    return (Y << 16)
+        | (Cb << 8)
+        | (Cr);
 }

package/src/core/color/illuminant/D65_spd_analytical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"D65_spd_analytical.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/illuminant/D65_spd_analytical.js"],"names":[],"mappings":"AA+CA;;;;;;;;;GASG;AACH,kDAJW,MAAM,GACJ,MAAM,CAelB"}
+{"version":3,"file":"D65_spd_analytical.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/illuminant/D65_spd_analytical.js"],"names":[],"mappings":"AAuBA;;;;;;;;;GASG;AACH,kDAJW,MAAM,GACJ,MAAM,CAelB"}

package/src/core/color/illuminant/D65_spd_analytical.js

@@ -9,33 +9,9 @@
  * and is not a perfect blackbody. This function is the standard
  * *physical approximation*.
  */
+import { planckian_radiance } from "./planckian_radiance.js";
 
 const D65_ANALYTIC_T = 6504.0; // CCT for D65 in Kelvin
-const D65_ANALYTIC_C2 = 1.438776877e-2; // Second radiation constant (m·K)
-
-/**
- * Calculates the un-normalized spectral power for a given wavelength.
- * @param {number} lambda_m Wavelength in meters
- * @param {number} T Temperature in Kelvin
- * @returns {number} Relative spectral power
- */
-function planckian_radiance(lambda_m, T) {
-    const lambda_T = lambda_m * T;
-    const exponent = D65_ANALYTIC_C2 / lambda_T;
-
-    // Handle high exponents to prevent Math.exp from returning Infinity
-    if (exponent > 80.0) {
-        return 0.0;
-    }
-
-    const lambda_5 = Math.pow(lambda_m, 5);
-
-    // This can be simplified to just (1/lambda_5) because the
-    // rest of the numerator is a constant we are normalizing away.
-    const radiance = (1.0 / lambda_5) / (Math.exp(exponent) - 1.0);
-
-    return radiance;
-}
 
 // Pre-calculate the normalization factor:
 // This is the un-normalized value of the function at 560nm (560e-9 m),

package/src/core/color/illuminant/planckian_radiance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Calculates the spectral radiance power of a black body for a given wavelength.
+ * @param {number} lambda_m Wavelength in meters
+ * @param {number} T Temperature in Kelvin
+ * @returns {number} Relative spectral power
+ */
+export function planckian_radiance(lambda_m: number, T: number): number;
+//# sourceMappingURL=planckian_radiance.d.ts.map

package/src/core/color/illuminant/planckian_radiance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planckian_radiance.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/illuminant/planckian_radiance.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,6CAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAyBlB"}

package/src/core/color/illuminant/planckian_radiance.js

@@ -0,0 +1,41 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Second radiation constant (m·K)
+ *
+ * `c2 = (h*c) / (kb)`
+ *
+ * Value is meters Kelvin (m*K).
+ */
+const PLANCK_C2 = 1.438776877e-2;
+
+/**
+ * Calculates the spectral radiance power of a black body for a given wavelength.
+ * @param {number} lambda_m Wavelength in meters
+ * @param {number} T Temperature in Kelvin
+ * @returns {number} Relative spectral power
+ */
+export function planckian_radiance(lambda_m, T) {
+    assert.isNumber(lambda_m, 'lambda_m');
+    assert.notNaN(lambda_m, 'lambda_m');
+    
+    assert.isNumber(T, 'T');
+    assert.notNaN(T, 'T');
+
+    const lambda_T = lambda_m * T;
+    const exponent = PLANCK_C2 / lambda_T;
+
+    // Handle high exponents to prevent Math.exp from returning Infinity
+    if (exponent > 80.0) { // exp(80) = ~5.5e34
+        // this would pull denominator to extremely high values, effectively driving the result towards 0
+        return 0.0;
+    }
+
+    const lambda_5 = Math.pow(lambda_m, 5);
+
+    // This can be simplified to just (1/lambda_5) because the
+    // rest of the numerator is a constant we are normalizing away.
+    const radiance = (1.0 / lambda_5) / (Math.exp(exponent) - 1.0);
+
+    return radiance;
+}

package/src/core/color/kelvin/kelvin_to_rgb.d.ts

@@ -1,10 +1,17 @@
 /**
- * @see https://www.zombieprototypes.com/?p=210
- * @see https://tannerhelland.com/2012/09/18/convert-temperature-rgb-algorithm-code.html
- * TODO: not sure if output is in linear or sRGB space, looking at the way colors look in Unity - it appears that colors are in sRGB and need to be shifted to linear before being used
- * @param {number[]} result RGB output
+ *
+ * Converts Kelvin temperature to RGB.
+ * Handles ranges 0K - 40000K
+ *
+ * Note: if you will need to covert the output to linear space ({@link sRGB_to_linear}) if you intend to perform any mixing on the color.
+ *
+ * @param {number[]} result result RGB output (sRGB Gamma Corrected)
  * @param {number} result_offset
  * @param {number} temperature in Kelvin
+ *
+ * @see https://www.zombieprototypes.com/?p=210
+ * @see https://tannerhelland.com/2012/09/18/convert-temperature-rgb-algorithm-code.html
+ * @see sRGB_to_linear
  */
 export function kelvin_to_rgb(result: number[], result_offset: number, temperature: number): void;
 //# sourceMappingURL=kelvin_to_rgb.d.ts.map

package/src/core/color/kelvin/kelvin_to_rgb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kelvin_to_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/kelvin/kelvin_to_rgb.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,sCAJW,MAAM,EAAE,iBACR,MAAM,eACN,MAAM,QAkDhB"}
+{"version":3,"file":"kelvin_to_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/kelvin/kelvin_to_rgb.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;GAcG;AACH,sCARW,MAAM,EAAE,iBACR,MAAM,eACN,MAAM,QA6DhB"}

package/src/core/color/kelvin/kelvin_to_rgb.js

@@ -1,13 +1,110 @@
 import { assert } from "../../assert.js";
 import { clamp01 } from "../../math/clamp01.js";
+import { inverseLerp } from "../../math/inverseLerp.js";
+import { lerp } from "../../math/lerp.js";
+
 
 /**
- * @see https://www.zombieprototypes.com/?p=210
- * @see https://tannerhelland.com/2012/09/18/convert-temperature-rgb-algorithm-code.html
- * TODO: not sure if output is in linear or sRGB space, looking at the way colors look in Unity - it appears that colors are in sRGB and need to be shifted to linear before being used
- * @param {number[]} result RGB output
+ * Red-dominant approximation
+ *
+ * Valid for < 6600K
+ *
+ * @param {number[]} out
+ * @param {number} t K/100
+ */
+function approximate_regime_red(out, t) {
+
+    const r = 1;
+
+    const g = clamp01(
+        -0.6088425710866344 - 0.001748900018414868 * (t - 2) + 0.4097731842899564 * Math.log(t - 2)
+    );
+
+    const b = t <= 20 ? 0 : clamp01(
+        -0.9990954974165059 + 0.0032447435545127036 * (t - 10) + 0.453646839257496 * Math.log(t - 10)
+    );
+
+    out[0] = r;
+    out[1] = g;
+    out[2] = b;
+}
+
+
+/**
+ * Blue-dominant approximation
+ *
+ * Valid for > 6600K
+ *
+ * @param {number[]} out
+ * @param {number} t K/100
+ */
+function approximate_regime_blue(out, t) {
+
+    const r = clamp01(
+        1.3803015908551253 + 0.0004478684462124118 * (t - 55) - 0.15785750232675008 * Math.log(t - 55)
+    ); // in normalized scale
+
+    const g = clamp01(
+        1.2762722061615583 + 0.0003115080994769546 * (t - 50) - 0.11013841706194392 * Math.log(t - 50)
+    );
+
+    const b = 1;
+
+    out[0] = r;
+    out[1] = g;
+    out[2] = b;
+}
+
+/**
+ * Black body
+ *
+ * Valid for < 1000K
+ *
+ * @param {number[]} out
+ * @param {number} t K/100
+ */
+function approximate_regime_blackbody(out, t) {
+    // 1. Handle "Black Body" cooling (below 1000K)
+
+    // These are the values the algorithm produces at exactly 1000K (t=10).
+    // We lock the hue here and just fade the brightness to zero.
+    const k1000_r = 1;
+    const k1000_g = 0.22926561084500907;
+    const k1000_b = 0;
+
+    // The Draper point (approx 798K) is where objects begin to glow visible red.
+    const DRAPER_POINT = 7.98; // 798K
+
+    // Note: We are attenuating Gamma-corrected values here.
+    // Physically strictly incorrect (should be linear), but visually acceptable
+    // and faster for this specific "fade to black" effect.
+    const brightness = Math.max(0, inverseLerp(DRAPER_POINT, 10, t));
+
+    out[0] = k1000_r * brightness;
+    out[1] = k1000_g * brightness;
+    out[2] = k1000_b * brightness;
+}
+
+/**
+ * Avoid heap allocation in the main function
+ * @type {number[]}
+ */
+const scratch_rgb = [0, 0, 0];
+
+/**
+ *
+ * Converts Kelvin temperature to RGB.
+ * Handles ranges 0K - 40000K
+ *
+ * Note: if you will need to covert the output to linear space ({@link sRGB_to_linear}) if you intend to perform any mixing on the color.
+ *
+ * @param {number[]} result result RGB output (sRGB Gamma Corrected)
  * @param {number} result_offset
  * @param {number} temperature in Kelvin
+ *
+ * @see https://www.zombieprototypes.com/?p=210
+ * @see https://tannerhelland.com/2012/09/18/convert-temperature-rgb-algorithm-code.html
+ * @see sRGB_to_linear
  */
 export function kelvin_to_rgb(
     result,
@@ -18,43 +115,50 @@ export function kelvin_to_rgb(
     assert.isNonNegativeInteger(result_offset, "result_offset");
     assert.isNumber(temperature, "temperature");
 
-    let r;
-    let g;
-    let b;
-
     // Temperature divided by 100 for calculations
     const t = temperature / 100;
 
-    if (t <= 66) {
-        r = 1;
+    if (t < 10) {
 
-        g = clamp01(
-            -0.6088425710866344 - 0.001748900018414868 * (t - 2) + 0.4097731842899564 * Math.log(t - 2)
-        );
+        approximate_regime_blackbody(scratch_rgb, t);
+
+    } else {
+
+        const BLEND_MIN = 65;
+        const BLEND_MAX = 67;
+
+        if (t < BLEND_MIN) {
+
+            approximate_regime_red(scratch_rgb, t);
+
+        } else if (t > BLEND_MAX) {
+
+            approximate_regime_blue(scratch_rgb, t);
 
-        if (t <= 20) {
-            b = 0;
         } else {
 
-            b = clamp01(
-                -0.9990954974165059 + 0.0032447435545127036 * (t - 10) + 0.453646839257496 * Math.log(t - 10)
-            );
+            // blend the two regimes to avoid discontinuity
+            const alpha = inverseLerp(BLEND_MIN, BLEND_MAX, t);
 
-        }
-    } else {
+            approximate_regime_red(scratch_rgb, t);
+            const r0 = scratch_rgb[0];
+            const g0 = scratch_rgb[1];
+            const b0 = scratch_rgb[2];
 
-        r = clamp01(
-            1.3803015908551253 + 0.0004478684462124118 * (t - 55) - 0.15785750232675008 * Math.log(t - 55)
-        ); // in normalized scale
+            approximate_regime_blue(scratch_rgb, t);
+            const r1 = scratch_rgb[0];
+            const g1 = scratch_rgb[1];
+            const b1 = scratch_rgb[2];
 
-        g = clamp01(
-            1.2762722061615583 + 0.0003115080994769546 * (t - 50) - 0.11013841706194392 * Math.log(t - 50)
-        );
+            scratch_rgb[0] = lerp(r0, r1, alpha);
+            scratch_rgb[1] = lerp(g0, g1, alpha);
+            scratch_rgb[2] = lerp(b0, b1, alpha);
+
+        }
 
-        b = 1;
     }
 
-    result[result_offset + 0] = r;
-    result[result_offset + 1] = g;
-    result[result_offset + 2] = b;
+    result[result_offset + 0] = scratch_rgb[0];
+    result[result_offset + 1] = scratch_rgb[1];
+    result[result_offset + 2] = scratch_rgb[2];
 }

package/src/core/color/kelvin/rgb_to_kelvin.d.ts

@@ -1,8 +1,11 @@
 /**
+ * Estimates the Color Temperature (Kelvin) from an RGB input.
  *
- * @see https://www.zombieprototypes.com/?p=210
  * @param {number[]|ArrayLike<number>|{0:number,1:number,2:number}} input input array
  * @param {number} [input_offset=0] offset into input array
+ * @returns {number} Temperature in Kelvin (approx 1000 to 40000)
+ *
+ * @see https://www.zombieprototypes.com/?p=210
  */
 export function rgb_to_kelvin(input: number[] | ArrayLike<number> | {
     0: number;

package/src/core/color/kelvin/rgb_to_kelvin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb_to_kelvin.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/kelvin/rgb_to_kelvin.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,qCAHW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,iBACvD,MAAM,UAwChB"}
+{"version":3,"file":"rgb_to_kelvin.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/kelvin/rgb_to_kelvin.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH,qCANW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,GAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,iBACvD,MAAM,GACJ,MAAM,CA4DlB"}

package/src/core/color/kelvin/rgb_to_kelvin.js

@@ -1,13 +1,20 @@
 import { assert } from "../../assert.js";
 import { kelvin_to_rgb } from "./kelvin_to_rgb.js";
 
+/**
+ * Save allocation with re-usable scratch
+ * @type {number[]}
+ */
 const scratch_rgb = [];
 
 /**
+ * Estimates the Color Temperature (Kelvin) from an RGB input.
  *
- * @see https://www.zombieprototypes.com/?p=210
  * @param {number[]|ArrayLike<number>|{0:number,1:number,2:number}} input input array
  * @param {number} [input_offset=0] offset into input array
+ * @returns {number} Temperature in Kelvin (approx 1000 to 40000)
+ *
+ * @see https://www.zombieprototypes.com/?p=210
  */
 export function rgb_to_kelvin(
     input,
@@ -17,32 +24,50 @@ export function rgb_to_kelvin(
     assert.isNonNegativeInteger(input_offset, "input_offset");
 
     const r = input[input_offset];
-    const g = input[input_offset + 1];
     const b = input[input_offset + 2];
 
-    const blue_red_ratio = b / r;
+    let minTemperature = 1000;
+    let maxTemperature = 40000;
+
+    if (r + b === 0) {
+        // black, effectively 0 Kelvin
+        return 0;
+    }
+
+    if (r === 0) {
+        // blue dominance, produce maximum
+        // also, avoid division by 0
+        return maxTemperature;
+    }
+
+    const expected_blue_red_ratio = b / r;
 
     // use solver to reverse function, slow but hey - it works
-    let temperature;
+    let temperature = 0;
 
     const epsilon = 0.4;
 
-    let minTemperature = 1000;
-    let maxTemperature = 40000;
-
+    // binary search
     while (maxTemperature - minTemperature > epsilon) {
 
         temperature = (maxTemperature + minTemperature) * 0.5;
 
         kelvin_to_rgb(scratch_rgb, 0, temperature);
 
-        const br = scratch_rgb[2] / scratch_rgb[0];
+        const actual_b = scratch_rgb[2];
+        const actual_r = scratch_rgb[0];
+
+        // prevent division by 0
+        const safe_r = Math.max(1e-7, actual_r);
 
-        if (br >= blue_red_ratio) {
+        const br = actual_b / safe_r;
+
+        if (br >= expected_blue_red_ratio) {
             maxTemperature = temperature;
         } else {
             minTemperature = temperature;
         }
+
     }
 
     return Math.round(temperature);

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

@@ -1,9 +1,12 @@
 /**
+ * Calculates Luminance (perceived brightness) using modern Rec.709 coefficients.
  *
- * @param {number} r
- * @param {number} g
- * @param {number} b
- * @return {number}
+ * Matches sRGB and HDTV standards.
+ *
+ * @param {number} r Red component (linear or gamma-corrected)
+ * @param {number} g Green component (linear or gamma-corrected)
+ * @param {number} b Blue component (linear or gamma-corrected)
+ * @return {number} The calculated luma value
  */
 export function rgb_to_luminance(r: number, g: number, b: number): number;
 //# sourceMappingURL=rgb_to_luminance.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rgb_to_luminance.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb_to_luminance.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oCALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAIjB"}
+{"version":3,"file":"rgb_to_luminance.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb_to_luminance.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,oCALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAIjB"}