From 19318576f360dcab9f151bd6ae45a4f8d17334a5 Mon Sep 17 00:00:00 2001
From: another-simple-pixel <anton.m.egorov@gmail.com>
Date: Wed, 13 May 2026 13:36:33 -0700
Subject: [PATCH] docs: clarify formula derivation and dev-only state

Three documentation/marker additions surfaced by an engineer-v1 audit:

- ChatWallpaper.kt: the per-mode/per-element constants used by the theme
  color formula were a wall of magic numbers. Add a header explaining
  what each parameter controls and where the values came from
  (empirically tuned via the dev UI in Appearance.kt).
- Appearance.kt: surround the module-level FormulaDevTools state
  (formulaSavedParams, patternScaleDragging) with a prominent banner
  marking it dev-only. The dev UI is shipped in the current build but
  must be removed before reaching end users; the search-tag makes that
  trivial later.
- Color.kt: solveCubic had no docstring; the 1e-10f thresholds looked
  like magic. Document Cardano's method, the maxChromaForMatrix caller
  context, and the numerical-stability rationale for the thresholds.

Pure comment additions; no behavior change.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../kotlin/chat/simplex/common/ui/theme/Color.kt    |  6 ++++++
 .../simplex/common/views/helpers/ChatWallpaper.kt   | 13 ++++++++++---
 .../simplex/common/views/usersettings/Appearance.kt | 12 ++++++++++--
 3 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/ui/theme/Color.kt b/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/ui/theme/Color.kt
index bd6a96f391..a37c47950a 100644
--- a/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/ui/theme/Color.kt
+++ b/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/ui/theme/Color.kt
@@ -148,6 +148,12 @@ private fun allChannelsInGamut(C: Float, p: FloatArray, q: FloatArray, matrix: A
   return true
 }
 
+/** Real roots of ax³+bx²+cx+d = 0 (Cardano's method).
+ *  Used by [maxChromaForMatrix] to find the gamut-boundary chroma at a given
+ *  (L, H) — the largest C such that oklch(L, C, H) is still inside the target
+ *  RGB cube. The 1e-10f thresholds detect near-zero leading coefficients to
+ *  avoid amplifying floating-point noise (degree drops from cubic to quadratic
+ *  to linear as coefficients vanish). */
 private fun solveCubic(a: Float, b: Float, c: Float, d: Float): FloatArray {
   if (abs(a) < 1e-10f) {
     if (abs(b) < 1e-10f) {
diff --git a/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ChatWallpaper.kt b/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ChatWallpaper.kt
index e7f0dc391a..c3a1334006 100644
--- a/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ChatWallpaper.kt
+++ b/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/helpers/ChatWallpaper.kt
@@ -300,9 +300,16 @@ fun wallpaperBackgrounds(
   )
 
 // ===== Theme color formula =====
-// L = mode.lBase + mode.lSpread * elem.lOffset
-// C = mode.cFactor * elem.cFactor * theme.cScale
-// H = theme.hue
+// Each preset's per-mode bubble/tint colors are derived from the preset's hue
+// and chroma scale, the mode's anchor (lBase) + range (lSpread) + chroma factor,
+// and the element's lightness offset + chroma factor. Constants below were tuned
+// empirically via the FormulaDevTools UI (see Appearance.kt) and locked in once
+// every preset/mode combination satisfied the design contrast targets.
+//
+// Formula:
+//   L = mode.lBase + mode.lSpread * elem.lOffset
+//   C = mode.cFactor * elem.cFactor * theme.cScale
+//   H = theme.hue
 
 private data class ModeParams(val lBase: Float, val lSpread: Float, val cFactor: Float)
 private data class ElemParams(val lOffset: Float, val cFactor: Float)
diff --git a/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/Appearance.kt b/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/Appearance.kt
index 64656a6bca..22f0bf45ed 100644
--- a/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/Appearance.kt
+++ b/apps/multiplatform/common/src/commonMain/kotlin/chat/simplex/common/views/usersettings/Appearance.kt
@@ -56,11 +56,19 @@ import kotlin.math.*
 @Composable
 expect fun AppearanceView(m: ChatModel)
 
-// Formula slider values — survives navigation, cleared on app restart
+// ─── DEV-ONLY: theme-formula tuning UI ─────────────────────────────────────
+// Module-level state below backs the FormulaDevTools panel that the founder
+// uses to live-tune wallpaper color formulas. It is NOT part of the user-facing
+// settings flow and MUST be removed (along with FormulaDevTools, FormulaSlider,
+// buildCodeOutput, formulaSavedParams, patternScaleDragging) before this PR's
+// dev affordances ship to end users. Search-tag: REMOVE-DEV-FORMULA.
+
+// Formula slider values — survives navigation, cleared on app restart.
 private val formulaSavedParams = mutableStateMapOf<String, Float>()
 
-// Desktop: use fast scaling during slider drag, SCALE_SMOOTH on release
+// Desktop: use fast scaling during slider drag, SCALE_SMOOTH on release.
 private var patternScaleDragging by mutableStateOf(false)
+// ───────────────────────────────────────────────────────────────────────────
 
 object AppearanceScope {
   @Composable