Add monochrome palette detection and fallback palette resolution

Co-authored-by: jongalloway <68539+jongalloway@users.noreply.github.com>
Agent-Logs-Url: https://github.com/jongalloway/DiagramForge/sessions/27f13f43-5376-482e-8812-a2b0189deafb

Author: Copilot

src/DiagramForge/Models/ColorUtils.cs

@@ -160,6 +160,72 @@ public static double GetContrastRatio(string hex1, string hex2)
         return (lighter + 0.05) / (darker + 0.05);
     }
 
+    // ── Achromatic / monochrome helpers ──────────────────────────────────────
+
+    /// <summary>
+    /// Returns <see langword="true"/> when the HSL saturation of the color is below
+    /// <paramref name="saturationThreshold"/>. Achromatic colors include pure white,
+    /// pure black, and grays.
+    /// </summary>
+    /// <param name="hex">Hex color string.</param>
+    /// <param name="saturationThreshold">
+    /// Saturation threshold 0–1; colors with saturation below this value are considered
+    /// achromatic. Defaults to 0.08.
+    /// </param>
+    public static bool IsAchromatic(string hex, double saturationThreshold = 0.08)
+    {
+        var (rRaw, gRaw, bRaw) = ParseHex(hex);
+        double r = rRaw / 255d;
+        double g = gRaw / 255d;
+        double b = bRaw / 255d;
+        double max = Math.Max(r, Math.Max(g, b));
+        double min = Math.Min(r, Math.Min(g, b));
+        double delta = max - min;
+        double lightness = (max + min) / 2;
+        double denominator = 1 - Math.Abs(2 * lightness - 1);
+        // When delta is near zero the color is already achromatic; guard the denominator
+        // (which is also ~0 at lightness=0 or lightness=1) to avoid division by zero.
+        double saturation = delta < 0.0001 || denominator < 0.0001
+            ? 0
+            : delta / denominator;
+        return saturation < saturationThreshold;
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> when all palette entries are achromatic,
+    /// all entries are the same color, or all entries match the background color.
+    /// This is the single check that layout engines should call before consuming
+    /// <see cref="Theme.NodePalette"/> directly.
+    /// </summary>
+    /// <param name="palette">Palette to evaluate (must not be <see langword="null"/>).</param>
+    /// <param name="backgroundColor">
+    /// Optional background color. When provided, a palette whose every entry matches
+    /// the background is considered monochrome (the nodes would be invisible).
+    /// </param>
+    /// <exception cref="ArgumentNullException"><paramref name="palette"/> is <see langword="null"/>.</exception>
+    public static bool IsPaletteMonochrome(IReadOnlyList<string> palette, string? backgroundColor = null)
+    {
+        ArgumentNullException.ThrowIfNull(palette);
+
+        if (palette.Count == 0)
+            return false;
+
+        // All entries are achromatic (white, black, or gray).
+        if (palette.All(c => IsAchromatic(c)))
+            return true;
+
+        // All entries are the same color (trivially monochrome — no hue variety).
+        if (palette.All(c => string.Equals(c, palette[0], StringComparison.OrdinalIgnoreCase)))
+            return true;
+
+        // All entries match the background (nodes would be invisible against the canvas).
+        if (backgroundColor is not null &&
+            palette.All(c => string.Equals(c, backgroundColor, StringComparison.OrdinalIgnoreCase)))
+            return true;
+
+        return false;
+    }
+
     // ── HSL helpers ───────────────────────────────────────────────────────────
 
     /// <summary>
@@ -354,16 +420,44 @@ private static string ExpandShorthand(string hex)
     /// (removing the shared "whiteness") and adding a small brightness floor.
     /// Useful when a pastel palette needs a bold accent variant (e.g. pillar titles).
     /// </summary>
+    /// <remarks>
+    /// When the input color is achromatic (no hue to amplify), a lightness shift is
+    /// applied instead: light achromatic inputs are darkened and dark achromatic inputs
+    /// are lightened to produce a visually distinguishable result. Callers that require
+    /// a chromatic output for achromatic inputs should use
+    /// <see cref="IsPaletteMonochrome"/> / <c>ThemePaletteResolver.ResolveEffectivePalette</c>
+    /// before calling this method.
+    /// </remarks>
     /// <param name="hex">Hex color string (typically a pastel).</param>
     /// <param name="amplify">How much to amplify the hue deviation (default 3).</param>
     public static string Vibrant(string hex, double amplify = 3.0)
     {
         var (r, g, b, a) = ParseHexWithAlpha(hex);
-        int min = Math.Min(r, Math.Min(g, b));
+
+        if (IsAchromatic(hex))
+        {
+            // Achromatic colors have no hue channel to amplify.
+            // Shift lightness toward mid-range so the result is visually
+            // distinguishable from both the input and a same-color background.
+            double max = Math.Max(r, Math.Max(g, b));
+            double min = Math.Min(r, Math.Min(g, b));
+            double lightness = (max + min) / (2.0 * 255);
+            // 0.5 splits light (≥0.5) from dark (<0.5).
+            // A shift of 0.35 reliably moves the result away from the input without
+            // pushing it all the way to the opposite extreme.
+            // The 0.25 / 0.75 bounds prevent the result landing too close to black or white.
+            double targetLightness = lightness >= 0.5
+                ? Math.Max(0.25, lightness - 0.35)
+                : Math.Min(0.75, lightness + 0.35);
+            int channel = (int)Math.Round(targetLightness * 255);
+            return ToHex(channel, channel, channel, a);
+        }
+
+        int minChannel = Math.Min(r, Math.Min(g, b));
         return ToHex(
-            Clamp((int)((r - min) * amplify + min / 4.0)),
-            Clamp((int)((g - min) * amplify + min / 4.0)),
-            Clamp((int)((b - min) * amplify + min / 4.0)),
+            Clamp((int)((r - minChannel) * amplify + minChannel / 4.0)),
+            Clamp((int)((g - minChannel) * amplify + minChannel / 4.0)),
+            Clamp((int)((b - minChannel) * amplify + minChannel / 4.0)),
             a);
     }
 

src/DiagramForge/Models/ThemePaletteResolver.cs

@@ -8,6 +8,111 @@ namespace DiagramForge.Models;
 /// </summary>
 public static class ThemePaletteResolver
 {
+    private const int DefaultPaletteSize = 8;
+
+    /// <summary>
+    /// Returns a palette suitable for direct node-fill use, regardless of whether
+    /// the theme's <see cref="Theme.NodePalette"/> is chromatic.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// If <see cref="Theme.NodePalette"/> is non-empty and
+    /// <see cref="ColorUtils.IsPaletteMonochrome"/> returns <see langword="false"/>,
+    /// the palette is returned unchanged.
+    /// </para>
+    /// <para>
+    /// When the palette is monochrome (all-white, all-black, all-same, or all matching
+    /// the background), a fallback palette is built:
+    /// <list type="number">
+    ///   <item>
+    ///     If <see cref="Theme.UseBorderGradients"/> is <see langword="true"/> and
+    ///     <see cref="Theme.BorderGradientStops"/> contains more than one stop, the stops
+    ///     are interpolated/cycled to produce <see cref="DefaultPaletteSize"/> entries.
+    ///   </item>
+    ///   <item>
+    ///     Otherwise, a palette is derived from <see cref="Theme.AccentColor"/> and
+    ///     <see cref="Theme.SecondaryColor"/> via hue rotation.
+    ///   </item>
+    /// </list>
+    /// </para>
+    /// <para>This is a pure function of the <see cref="Theme"/> — no side effects.</para>
+    /// </remarks>
+    /// <param name="theme">Source theme.</param>
+    /// <returns>
+    /// A <see cref="IReadOnlyList{T}"/> of hex color strings suitable for node fills.
+    /// </returns>
+    /// <exception cref="ArgumentNullException"><paramref name="theme"/> is <see langword="null"/>.</exception>
+    public static IReadOnlyList<string> ResolveEffectivePalette(Theme theme)
+    {
+        ArgumentNullException.ThrowIfNull(theme);
+
+        if (theme.NodePalette is { Count: > 0 } &&
+            !ColorUtils.IsPaletteMonochrome(theme.NodePalette, theme.BackgroundColor))
+            return theme.NodePalette;
+
+        // Build fallback from gradient stops when they are available and meaningful.
+        if (theme.UseBorderGradients && theme.BorderGradientStops is { Count: > 1 })
+            return BuildPaletteFromGradientStops(theme.BorderGradientStops, DefaultPaletteSize);
+
+        // Fall back to hue-rotation derivation from the theme's semantic colors.
+        return BuildPaletteFromHueRotation(theme.AccentColor, theme.SecondaryColor, DefaultPaletteSize);
+    }
+
+    // ── Private helpers ───────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Samples <paramref name="count"/> evenly-distributed colors from the gradient
+    /// by linearly interpolating between adjacent stop pairs.
+    /// </summary>
+    private static IReadOnlyList<string> BuildPaletteFromGradientStops(IReadOnlyList<string> stops, int count)
+    {
+        // Callers must supply at least two stops so there is an interpolatable range.
+        if (stops.Count < 2)
+            throw new ArgumentException("At least two gradient stops are required.", nameof(stops));
+
+        var result = new List<string>(count);
+
+        if (count == 1)
+        {
+            result.Add(stops[0]);
+            return result;
+        }
+
+        for (int i = 0; i < count; i++)
+        {
+            double t = (double)i / (count - 1);
+            double position = t * (stops.Count - 1);
+            int lo = Math.Min((int)Math.Floor(position), stops.Count - 2);
+            int hi = lo + 1;
+            double blend = position - lo;
+            result.Add(ColorUtils.Blend(stops[lo], stops[hi], blend));
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    /// Derives <paramref name="count"/> colors by rotating the hue of
+    /// <paramref name="accentColor"/> and <paramref name="secondaryColor"/>
+    /// in equal steps, alternating between the two base colors.
+    /// </summary>
+    private static IReadOnlyList<string> BuildPaletteFromHueRotation(
+        string accentColor, string secondaryColor, int count)
+    {
+        bool isLight = ColorUtils.IsLight(accentColor);
+        double hueStep = 360.0 / count;
+        var result = new List<string>(count);
+
+        for (int i = 0; i < count; i++)
+        {
+            string baseColor = i % 2 == 0 ? accentColor : secondaryColor;
+            double rotation = Math.Floor(i / 2.0) * hueStep;
+            result.Add(ColorUtils.RotateHue(baseColor, rotation, isLight));
+        }
+
+        return result;
+    }
+
     /// <summary>
     /// Builds an array of <paramref name="ringCount"/> visually distinct ring colors
     /// derived from the theme palette.