Honor real tint vs JPEG noise in monochrome palette generation

Two-way split based on detectMonochromeTint:
- Average chroma below MinMeaningfulTintChroma (0.008) -> pure grayscale.
  Fixes B&W JPEGs and near-grayscale photos that previously produced a
  blue palette from JPEG compression noise (3 of 16 samples with chroma
  0.005 clustered around hue 240 were enough to trip the old detector).
- Above the floor -> strong-tint generator. Removes the middle "subdued
  rainbow at chroma 0.06" path that produced six visibly different hues
  from images users perceived as monochrome (sepia paintings, faintly
  blue-green pixel art, themed wallpapers).

Strong-tint generator now uses synthesizeMonoBgIfMuddy for bg, so
Nord/Tokyo Night/sepia keep their image-derived background instead of
clamping to extreme lightness. Contrast guard catches pathological gray
inputs where darkest is close to lightest.

Author: bjarneo

internal/extraction/cache.go

@@ -48,16 +48,33 @@ func GetCacheKey(imagePath string, lightMode bool) string {
 	return fmt.Sprintf("%x", hash)
 }
 
+// modeCacheVersion is an optional per-mode suffix that lets us invalidate
+// cached palettes when a mode's generator algorithm changes. Cached entries
+// for older versions become orphaned but harmless — the next extraction
+// rebuilds at the new version. Bump when the generator output meaningfully
+// changes for a given mode.
+var modeCacheVersion = map[string]string{
+	"monochromatic": "v4", // strong-tint bg/fg now derived from image via synthesizeMonoBgIfMuddy
+	"normal":        "v5", // strong-tint routing threshold lowered + image-derived bg preserved
+}
+
 // buildCacheKey appends the mode suffix to a base cache key.
 // Returns "" when the base is "" (no caching possible) or falls through for "normal" mode.
 func buildCacheKey(base, mode string) string {
 	if base == "" {
 		return ""
 	}
 	if mode == "normal" {
+		if v, ok := modeCacheVersion["normal"]; ok {
+			return base + "_" + v
+		}
 		return base
 	}
-	return base + "_" + mode
+	key := base + "_" + mode
+	if v, ok := modeCacheVersion[mode]; ok {
+		key += "_" + v
+	}
+	return key
 }
 
 // GetMultiCacheKey generates a cache key for blended extraction across multiple images.

internal/extraction/constants.go

@@ -22,8 +22,23 @@ const (
 	// Catches solid-color and near-monoharmonic wallpapers that aren't gray.
 	HueClusterMagnitudeThreshold = 0.85
 
-	// Monochrome tint
-	MonochromeTintStrength = 0.15
+	// Monochrome tint pulls the canonical ANSI hue targets toward the image's
+	// dominant hue. The auto-detected monochrome path uses a mild pull
+	// (`MonochromeTintStrength`) so colors stay recognisable. The explicit
+	// `monochromatic` mode uses a much stronger pull (`MonochromaticTintStrength`)
+	// to produce a more unified mood while keeping the 6 ANSI slots
+	// distinguishable for syntax highlighting.
+	MonochromeTintStrength    = 0.15
+	MonochromaticTintStrength = 0.65
+
+	// MinMeaningfulTintChroma: minimum *average* chroma across all dominant
+	// samples for `detectMonochromeTint` to consider the image actually
+	// tinted. JPEG compression can leave a few samples with chroma
+	// 0.003-0.008 in an otherwise-grayscale photo; without this floor the
+	// detector calls a strongly-clustered noise band "a tint" and produces
+	// a blue palette from a black-and-white image. Above this floor the
+	// image is treated as a unified mono mood; below, pure grayscale.
+	MinMeaningfulTintChroma = 0.008
 
 	// OKLCH scoring thresholds
 	MinChromaForAnsiMatch = 0.035 // Minimum OKLCH chroma for a valid ANSI color match

internal/extraction/palette_monochrome.go

@@ -25,10 +25,26 @@ func synthesizeMonoBgIfMuddy(bgColor string, lightMode bool) string {
 }
 
 // detectMonochromeTint detects the dominant tint hue from mostly-gray colors
-// using weighted circular mean in OKLCH space. Colors with more chroma get more weight.
-func detectMonochromeTint(colors []string) (hue float64, hasTint bool) {
+// using weighted circular mean in OKLCH space. Colors with more chroma get
+// more weight.
+//
+// Returns:
+//   - hue: mean tint direction (degrees, 0-360), undefined when hasTint=false.
+//   - hasTint: true when the image has a meaningful color cast above
+//     the JPEG-noise floor. A near-grayscale JPEG may still have a few
+//     samples with chroma 0.003-0.008 from compression artifacts; treating
+//     those as "tint" produces a blue palette from a black-and-white photo.
+//   - tintStrength: how strongly the tint manifests, computed as
+//     concentration * average chroma. concentration alone identifies a
+//     tightly-clustered cast (sepia, blueprint) but doesn't distinguish it
+//     from clustered noise; multiplying by chroma weights real color above
+//     JPEG-grade noise. In [0, ~0.3] for realistic inputs.
+func detectMonochromeTint(colors []string) (hue float64, hasTint bool, tintStrength float64) {
+	if len(colors) == 0 {
+		return 0, false, 0
+	}
 	var sinSum, cosSum float64
-	var totalWeight float64
+	var chromaSum float64
 
 	for _, c := range colors {
 		lch := color.HexToOKLCH(c)
@@ -37,120 +53,173 @@ func detectMonochromeTint(colors []string) (hue float64, hasTint bool) {
 			rad := lch.H * math.Pi / 180
 			sinSum += math.Sin(rad) * weight
 			cosSum += math.Cos(rad) * weight
-			totalWeight += weight
+			chromaSum += weight
 		}
 	}
 
-	if totalWeight < 0.001 {
-		return 0, false
+	// Average chroma across ALL dominant samples (not just the chromatic
+	// ones). A near-grayscale image dominated by C≈0 pixels yields a very
+	// low average even if its handful of noisy samples cluster perfectly.
+	avgChroma := chromaSum / float64(len(colors))
+	if avgChroma < MinMeaningfulTintChroma {
+		return 0, false, 0
 	}
 
-	avgHue := math.Mod(math.Atan2(sinSum/totalWeight, cosSum/totalWeight)*180/math.Pi+360, 360)
-	return avgHue, true
+	meanSin := sinSum / chromaSum
+	meanCos := cosSum / chromaSum
+	avgHue := math.Mod(math.Atan2(meanSin, meanCos)*180/math.Pi+360, 360)
+	concentration := math.Sqrt(meanSin*meanSin + meanCos*meanCos)
+	return avgHue, true, concentration * avgChroma
 }
 
-// applyTint applies tint influence to an OKLCH hue based on the image's dominant tone.
+// applyTint applies tint influence to an OKLCH hue based on the image's
+// dominant tone, at the strength used by the auto-detected monochrome path.
 func applyTint(ansiHue, tintHue float64, hasTint bool) float64 {
+	return applyTintStrength(ansiHue, tintHue, hasTint, MonochromeTintStrength)
+}
+
+// applyTintStrength is the parameterised form: `strength` is in [0, 1] where
+// 0 leaves the canonical ANSI hue alone and 1 snaps fully to the image hue.
+// The explicit `monochromatic` mode uses a higher strength to produce a
+// stronger unified mood while keeping ANSI slots distinguishable.
+func applyTintStrength(ansiHue, tintHue float64, hasTint bool, strength float64) float64 {
 	if !hasTint {
 		return ansiHue
 	}
 	hueDiff := math.Mod(tintHue-ansiHue+540, 360) - 180
-	return math.Mod(ansiHue+hueDiff*MonochromeTintStrength+360, 360)
+	return math.Mod(ansiHue+hueDiff*strength+360, 360)
 }
 
-// GenerateMonochromePalette generates a monochrome ANSI palette with distinguishable
-// hue-tinted colors. Uses OKLCH hue targets at subdued chroma so colors remain
-// functional for syntax highlighting while matching the monochrome mood.
+// GenerateMonochromePalette generates a palette for auto-detected monochrome
+// images. Two-way split:
+//
+//   - hasTint=false: fully achromatic (B&W JPEGs, line art) → pure grayscale.
+//   - hasTint=true:  has a real color cast (sepia, blueprint, faint blue
+//     pixel art, themed wallpaper) → strong-tint generator.
+//
+// The previous middle "subdued rainbow at chroma 0.06" path was removed
+// because users perceived it as wrong: an image they read as monochrome
+// produced six visibly-different hues. detectMonochromeTint's
+// MinMeaningfulTintChroma floor already filters out JPEG-noise tints, so
+// anything reaching the tinted branch is something the user wants
+// reflected as a unified mono mood.
 func GenerateMonochromePalette(grayColors []string, lightMode bool) [16]string {
-	sortedByLightness := SortColorsByLightness(grayColors)
+	tintHue, hasTint, _ := detectMonochromeTint(grayColors)
+	if !hasTint {
+		return generateGrayscaleMonochromaticPalette(grayColors, lightMode)
+	}
+	return generateTintedMonochromaticPalette(grayColors, lightMode, tintHue)
+}
+
+// GenerateMonochromaticPalette generates a monochromatic-mood ANSI palette
+// keyed on the image's dominant hue. Background, foreground, the comment
+// gray, and the high-contrast endpoint sit on the base hue (the "mono"
+// feel), and the 6 ANSI slots use canonical hue targets pulled strongly
+// toward the base hue — so red still reads as red and green still reads as
+// green, just biased toward the image's tone.
+//
+// For fully achromatic images (B&W photos, line art, grayscale renders),
+// detectMonochromeTint returns hasTint=false; we fall through to a true
+// grayscale palette so the result actually feels monochrome instead of
+// arbitrarily pulling every ANSI slot toward extractDominantHue's red
+// fallback.
+func GenerateMonochromaticPalette(dominantColors []string, lightMode bool) [16]string {
+	tintHue, hasTint, _ := detectMonochromeTint(dominantColors)
+	if !hasTint {
+		return generateGrayscaleMonochromaticPalette(dominantColors, lightMode)
+	}
+	return generateTintedMonochromaticPalette(dominantColors, lightMode, tintHue)
+}
+
+// generateGrayscaleMonochromaticPalette builds a pure-grayscale palette for
+// images with no usable hue. ANSI 1-6 are a lightness stair of neutral grays
+// rather than tinted versions of canonical hues — for a true B&W source the
+// "mono" mood IS the absence of color.
+func generateGrayscaleMonochromaticPalette(dominantColors []string, lightMode bool) [16]string {
+	sortedByLightness := SortColorsByLightness(dominantColors)
 	darkest := sortedByLightness[0]
 	lightest := sortedByLightness[len(sortedByLightness)-1]
-	tintHue, hasTint := detectMonochromeTint(grayColors)
 
 	var palette [16]string
 
-	// Mono path treats the image AS the theme — keep image-derived bg unless it's
-	// genuinely muddy (L > 0.35 dark / < 0.75 light), so themed wallpapers
-	// (Nord, Tokyo Night, etc.) keep their authentic colors.
 	if lightMode {
-		palette[0] = synthesizeMonoBgIfMuddy(lightest.Color, lightMode)
-		palette[7] = darkest.Color
+		palette[0] = color.OKLCHToHex(color.OKLCH{L: math.Max(0.94, lightest.Lightness), C: 0, H: 0})
+		palette[7] = color.OKLCHToHex(color.OKLCH{L: math.Min(0.22, darkest.Lightness), C: 0, H: 0})
 	} else {
-		palette[0] = synthesizeMonoBgIfMuddy(darkest.Color, lightMode)
-		palette[7] = lightest.Color
+		palette[0] = color.OKLCHToHex(color.OKLCH{L: math.Min(0.14, darkest.Lightness), C: 0, H: 0})
+		palette[7] = color.OKLCHToHex(color.OKLCH{L: math.Max(0.88, lightest.Lightness), C: 0, H: 0})
 	}
 
-	if color.ContrastRatio(palette[0], palette[7]) < MinFgBgContrast {
-		bgLab := color.HexToOKLab(palette[0])
-		fgLab := color.HexToOKLab(palette[7])
-		if bgLab.L < 0.5 {
-			fgLab.L = 0.97
-		} else {
-			fgLab.L = 0.05
-		}
-		palette[7] = color.OKLabToHex(fgLab)
-	}
-
-	// ANSI colors 1-6: use OKLCH hue targets with subdued chroma, tinted toward image tone
-	lightnessBase := 0.62
+	// Lightness stair for ANSI 1-6. Distinguishable by L only.
+	lightnessStair := [6]float64{0.35, 0.45, 0.55, 0.65, 0.75, 0.85}
 	if lightMode {
-		lightnessBase = 0.48
+		// Mirror around 0.5 so darker grays still contrast against light bg.
+		lightnessStair = [6]float64{0.65, 0.55, 0.45, 0.35, 0.25, 0.15}
 	}
-	for i := 0; i < len(OKLCHAnsiHues); i++ {
-		hue := applyTint(OKLCHAnsiHues[i], tintHue, hasTint)
-		lightness := lightnessBase + (float64(i)-2.5)*0.03
-		chroma := 0.06 // Subdued but visible for syntax highlighting
-		palette[i+1] = color.OKLCHToHex(color.OKLCH{L: lightness, C: chroma, H: hue})
+	for i := 0; i < 6; i++ {
+		palette[i+1] = color.OKLCHToHex(color.OKLCH{L: lightnessStair[i], C: 0, H: 0})
 	}
 
-	// Color 8: neutral gray for comments with guaranteed contrast
 	palette[8] = generateCommentColor(palette[0])
 
-	// Colors 9-14: brighter, slightly more chromatic versions of 1-6
-	for i := 0; i < len(OKLCHAnsiHues); i++ {
-		hue := applyTint(OKLCHAnsiHues[i], tintHue, hasTint)
-		baseLightness := lightnessBase + (float64(i)-2.5)*0.03
-		adjustment := 0.05
+	// Bright variants: nudge toward the high-contrast end of the stair.
+	for i := 0; i < 6; i++ {
+		bump := 0.08
 		if lightMode {
-			adjustment = -0.05
+			bump = -0.08
 		}
-		lightness := math.Max(0, math.Min(1, baseLightness+adjustment))
-		chroma := 0.08 // Slightly more chromatic than base
-		palette[i+9] = color.OKLCHToHex(color.OKLCH{L: lightness, C: chroma, H: hue})
+		l := math.Max(0.05, math.Min(0.95, lightnessStair[i]+bump))
+		palette[i+9] = color.OKLCHToHex(color.OKLCH{L: l, C: 0, H: 0})
 	}
 
-	// Color 15: near-white or near-black
 	if lightMode {
-		palette[15] = color.OKLCHToHex(color.OKLCH{L: math.Max(0.05, darkest.Lightness-0.05), C: 0.01, H: tintHue})
+		palette[15] = color.OKLCHToHex(color.OKLCH{L: 0.04, C: 0, H: 0})
 	} else {
-		palette[15] = color.OKLCHToHex(color.OKLCH{L: math.Min(0.98, lightest.Lightness+0.05), C: 0.01, H: tintHue})
+		palette[15] = color.OKLCHToHex(color.OKLCH{L: 0.99, C: 0, H: 0})
 	}
 
 	return palette
 }
 
-// GenerateMonochromaticPalette generates a monochromatic ANSI palette based on
-// the dominant hue from the image, with all colors sharing that hue at varying
-// chroma and lightness levels.
-func GenerateMonochromaticPalette(dominantColors []string, lightMode bool) [16]string {
-	baseHue := extractDominantHue(dominantColors)
+// generateTintedMonochromaticPalette is the chromatic path: there's a real
+// tint to anchor the mood, so ANSI 1-6 use canonical hues pulled toward it.
+// Bg / fg are derived from the actual image colors via synthesizeMonoBgIfMuddy,
+// which keeps themed-wallpaper backgrounds (Nord L≈0.30, Tokyo Night L≈0.21,
+// solarized L≈0.85) intact and only synthesizes a near-black/near-white bg
+// when the image's bg is genuinely too muddy to use as-is.
+func generateTintedMonochromaticPalette(dominantColors []string, lightMode bool, baseHue float64) [16]string {
 	sortedByLightness := SortColorsByLightness(dominantColors)
 	darkest := sortedByLightness[0]
 	lightest := sortedByLightness[len(sortedByLightness)-1]
 
 	var palette [16]string
 
+	// Bg / fg: prefer image-derived colors, only synthesize when muddy.
+	// This preserves authored themed-wallpaper backgrounds in mono mode.
 	if lightMode {
-		palette[0] = color.OKLCHToHex(color.OKLCH{L: math.Max(0.90, lightest.Lightness), C: 0.015, H: baseHue})
-		palette[7] = color.OKLCHToHex(color.OKLCH{L: math.Min(0.30, darkest.Lightness+0.05), C: 0.04, H: baseHue})
+		palette[0] = synthesizeMonoBgIfMuddy(lightest.Color, lightMode)
+		palette[7] = darkest.Color
 	} else {
-		palette[0] = color.OKLCHToHex(color.OKLCH{L: math.Min(0.18, darkest.Lightness), C: 0.025, H: baseHue})
-		palette[7] = color.OKLCHToHex(color.OKLCH{L: math.Max(0.85, lightest.Lightness-0.05), C: 0.02, H: baseHue})
+		palette[0] = synthesizeMonoBgIfMuddy(darkest.Color, lightMode)
+		palette[7] = lightest.Color
+	}
+
+	// Contrast guard for pathological inputs (gray photos where darkest and
+	// lightest are close together): if fg/bg contrast is below the readable
+	// floor, force fg toward the opposite extreme.
+	if color.ContrastRatio(palette[0], palette[7]) < MinFgBgContrast {
+		bgLab := color.HexToOKLab(palette[0])
+		fgLab := color.HexToOKLab(palette[7])
+		if bgLab.L < 0.5 {
+			fgLab.L = 0.97
+		} else {
+			fgLab.L = 0.05
+		}
+		palette[7] = color.OKLabToHex(fgLab)
 	}
 
-	// Colors 1-6: chroma stair from subtle to vivid, all at the same hue.
-	// Spread is 0.06–0.18 (well above OKLCH JND ~0.02) so slots are visibly distinct.
-	chromaLevels := [6]float64{0.06, 0.10, 0.14, 0.08, 0.12, 0.18}
+	// ANSI 1-6: canonical hues pulled strongly toward the base hue.
+	chromaLevels := [6]float64{0.09, 0.11, 0.13, 0.10, 0.12, 0.14}
 	lightnessOffsets := [6]float64{-0.08, -0.02, +0.04, +0.10, -0.05, +0.07}
 	lightnessBase := 0.62
 	if lightMode {
@@ -159,25 +228,24 @@ func GenerateMonochromaticPalette(dominantColors []string, lightMode bool) [16]s
 
 	for i := 0; i < 6; i++ {
 		lightness := math.Max(0.30, math.Min(0.85, lightnessBase+lightnessOffsets[i]))
-		palette[i+1] = color.OKLCHToHex(color.OKLCH{L: lightness, C: chromaLevels[i], H: baseHue})
+		hue := applyTintStrength(OKLCHAnsiHues[i], baseHue, true, MonochromaticTintStrength)
+		palette[i+1] = color.OKLCHToHex(color.OKLCH{L: lightness, C: chromaLevels[i], H: hue})
 	}
 
-	// Color 8: comment gray
 	palette[8] = generateCommentColor(palette[0])
 
-	// Colors 9-14: brighter versions
-	brightChromaLevels := [6]float64{0.09, 0.13, 0.17, 0.11, 0.15, 0.20}
+	brightChromaLevels := [6]float64{0.11, 0.14, 0.16, 0.12, 0.15, 0.17}
 	for i := 0; i < 6; i++ {
 		baseLightness := lightnessBase + lightnessOffsets[i]
 		adjustment := 0.10
 		if lightMode {
 			adjustment = -0.10
 		}
 		lightness := math.Max(0.20, math.Min(0.92, baseLightness+adjustment))
-		palette[i+9] = color.OKLCHToHex(color.OKLCH{L: lightness, C: brightChromaLevels[i], H: baseHue})
+		hue := applyTintStrength(OKLCHAnsiHues[i], baseHue, true, MonochromaticTintStrength)
+		palette[i+9] = color.OKLCHToHex(color.OKLCH{L: lightness, C: brightChromaLevels[i], H: hue})
 	}
 
-	// Color 15: maximum-contrast endpoint (near-white in dark mode, near-black in light mode)
 	if lightMode {
 		palette[15] = color.OKLCHToHex(color.OKLCH{L: 0.08, C: 0.03, H: baseHue})
 	} else {