From 09015b31cfb05f123d181e70dc6cb440dbabc1fa Mon Sep 17 00:00:00 2001
From: Patrick Schaper <patrick.schaper@aoe.com>
Date: Wed, 10 Jun 2026 15:38:49 +0200
Subject: [PATCH] fix(renderer): avoid pure white rain highlights

- cap red and blue highlight channels below xterm white

- document the xterm cube quantization constraint

- add regression checks for the palette highlight colors
---
 .../MatrixScreenSaver/NativeMatrixRenderer.swift    |  8 ++++++--
 .../NativeMatrixRendererTests.swift                 | 13 +++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/Sources/MatrixScreenSaver/NativeMatrixRenderer.swift b/Sources/MatrixScreenSaver/NativeMatrixRenderer.swift
index 72176da..ef2927c 100644
--- a/Sources/MatrixScreenSaver/NativeMatrixRenderer.swift
+++ b/Sources/MatrixScreenSaver/NativeMatrixRenderer.swift
@@ -1293,12 +1293,16 @@ final class NativeMatrixRenderer {
             }
 
             if minimum + 1 < levels {
+                // The xterm cube quantizes each channel to 6 steps (0, 95, 135,
+                // 175, 215, 255). A 0.95 cap still rounds back up to 255, so the
+                // highlight must stay below 0.9 to avoid pure white.
+                let highlightCap = 0.89
                 for level in (minimum + 1)..<levels {
                     let remaining = Double(levels - 1 - level)
                     let denominator = Double(levels - 1 - minimum)
-                    let r = 1.0 - (1.0 - Double(red) / edge) * (remaining / denominator)
+                    let r = highlightCap - (highlightCap - Double(red) / edge) * (remaining / denominator)
                     let g = 1.0 - (1.0 - Double(green) / edge) * (remaining / denominator)
-                    let b = 1.0 - (1.0 - Double(blue) / edge) * (remaining / denominator)
+                    let b = highlightCap - (highlightCap - Double(blue) / edge) * (remaining / denominator)
                     indices.append(color2index(r, g, b, levels: levels))
                 }
             }
diff --git a/Tests/MatrixScreenSaverTests/NativeMatrixRendererTests.swift b/Tests/MatrixScreenSaverTests/NativeMatrixRendererTests.swift
index 894582f..576e5f5 100644
--- a/Tests/MatrixScreenSaverTests/NativeMatrixRendererTests.swift
+++ b/Tests/MatrixScreenSaverTests/NativeMatrixRendererTests.swift
@@ -2,6 +2,19 @@ func nativeMatrixRendererTests() {
     ok(NativeMatrixRenderer().seedOffset == 0,
        "NativeMatrixRenderer: seedOffset defaults to 0")
 
+    let palette = NativeMatrixRenderer().levelColors
+    let hasNoPureWhite = !palette.contains { color in
+        color.red == 255 && color.green == 255 && color.blue == 255
+    }
+    ok(hasNoPureWhite,
+       "NativeMatrixRenderer: palette avoids pure white highlight")
+
+    let hasMaxGreenHighlight = palette.contains { color in
+        color.green == 255
+    }
+    ok(hasMaxGreenHighlight,
+       "NativeMatrixRenderer: palette keeps max-green highlight")
+
     let r1: NativeMatrixRenderer = .init()
     let r2: NativeMatrixRenderer = .init()
     r1.seedOffset = 0