From f90a2f0fe82891da4c93490abaa66d3627b6e9d9 Mon Sep 17 00:00:00 2001
From: "boston-ai-agent[bot]"
 <299475768+boston-ai-agent[bot]@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:49:21 +0200
Subject: [PATCH] fix(ui): resolve page palette before first paint (#54)

---
 docs/theme-first-paint.md                     |   5 +
 src/HelpDesk.NewWeb/Components/App.razor      |  71 +++++++++++-
 .../Layout/ThemePreferenceProvider.razor      |  19 +++-
 .../Themes/RatelDeskPrepaintTheme.cs          | 106 ++++++++++++++++++
 .../wwwroot/js/theme-preference.js            |  20 ----
 .../NewWeb/RatelDeskPrepaintThemeTests.cs     |  41 +++++++
 tests/ux/theme-first-paint.spec.ts            | 105 +++++++++++++++++
 7 files changed, 340 insertions(+), 27 deletions(-)
 create mode 100644 docs/theme-first-paint.md
 create mode 100644 src/HelpDesk.NewWeb/Themes/RatelDeskPrepaintTheme.cs
 delete mode 100644 src/HelpDesk.NewWeb/wwwroot/js/theme-preference.js
 create mode 100644 tests/Helpdesk.Tests/NewWeb/RatelDeskPrepaintThemeTests.cs
 create mode 100644 tests/ux/theme-first-paint.spec.ts
diff --git a/docs/theme-first-paint.md b/docs/theme-first-paint.md
new file mode 100644
index 00000000..c598102a
--- /dev/null
+++ b/docs/theme-first-paint.md
@@ -0,0 +1,5 @@
+# Theme first-paint contract
+
+`RatelDeskTheme` is the source of truth for both MudBlazor's runtime theme and the head-resident prepaint variables emitted by `RatelDeskPrepaintTheme`. The synchronous bootstrap normalizes the existing `helpdesk.theme.preference` value, resolves System against `prefers-color-scheme`, and sets the document attribute plus `color-scheme` before stylesheet and body parsing can paint visible application content.
+
+The prepaint selectors retain higher specificity than MudBlazor's initial `:root` variables, so the browser does not expose the provider's server-side light default while the interactive provider reads browser state. Runtime ownership then remains with `ThemePreferenceProvider`; it adopts the normalized preference, applies user selections safely even if storage is blocked, and retains System-mode OS change handling. The Playwright first-paint spec pauses only the Blazor runtime and observes real prerendered body/card/text colors before and after runtime release.
diff --git a/src/HelpDesk.NewWeb/Components/App.razor b/src/HelpDesk.NewWeb/Components/App.razor
index 916aaee3..d13302dd 100644
--- a/src/HelpDesk.NewWeb/Components/App.razor
+++ b/src/HelpDesk.NewWeb/Components/App.razor
@@ -4,13 +4,75 @@
 <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
     <base href="/" />  
+    <style id="helpdesk-prepaint-theme">@((MarkupString)RatelDeskPrepaintTheme.Css)</style>
     <script>
         (function () {
-            const key = "helpdesk.theme.preference";
-            const stored = window.localStorage.getItem(key);
-            const isDark = stored === "dark" || (stored !== "light" && window.matchMedia("(prefers-color-scheme: dark)").matches);
-            document.documentElement.dataset.helpdeskTheme = isDark ? "dark" : "light";
+            const storageKey = "helpdesk.theme.preference";
+
+            const normalize = (value) => typeof value === "string" ? value.trim().toLowerCase() : "system";
+            const storage = () => {
+                try {
+                    return window.localStorage;
+                } catch {
+                    return null;
+                }
+            };
+            const get = () => {
+                const availableStorage = storage();
+                if (!availableStorage) {
+                    return null;
+                }
+
+                try {
+                    return availableStorage.getItem(storageKey);
+                } catch {
+                    return null;
+                }
+            };
+            const systemTheme = () => {
+                try {
+                    return window.matchMedia?.("(prefers-color-scheme: dark)")?.matches ? "dark" : "light";
+                } catch {
+                    return "light";
+                }
+            };
+            const resolve = (value) => {
+                const preference = normalize(value);
+                return preference === "dark" || preference === "light" ? preference : systemTheme();
+            };
+            const apply = (value) => {
+                const theme = value === true || value === "dark" ? "dark" : "light";
+                document.documentElement.dataset.helpdeskTheme = theme;
+                document.documentElement.style.colorScheme = theme;
+                return theme;
+            };
+
+            window.helpdeskThemePreference = {
+                get: () => normalize(get()),
+                set: (value) => {
+                    const preference = normalize(value);
+                    const availableStorage = storage();
+                    if (!availableStorage) {
+                        return;
+                    }
+
+                    try {
+                        if (preference === "system") {
+                            availableStorage.removeItem(storageKey);
+                        } else {
+                            availableStorage.setItem(storageKey, preference);
+                        }
+                    } catch {
+                        // The in-memory selection is still applied by the caller.
+                    }
+                },
+                apply,
+                resolve
+            };
+
+            apply(resolve(get()));
         }());
     </script>
     <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" rel="stylesheet" />
@@ -40,7 +102,6 @@
     <script src=@Assets["_content/MudBlazor/MudBlazor.min.js"]></script>
     <script src=@Assets["_content/Extensions.MudBlazor.StaticInput/NavigationObserver.js"]></script>
     <script src="js/global-search-hotkeys.js"></script>
-    <script src="js/theme-preference.js"></script>
     <script>
         window.scrollToNotificationRow = function (id) {
             setTimeout(function () {
diff --git a/src/HelpDesk.NewWeb/Components/Layout/ThemePreferenceProvider.razor b/src/HelpDesk.NewWeb/Components/Layout/ThemePreferenceProvider.razor
index feb7322a..a22f4b78 100644
--- a/src/HelpDesk.NewWeb/Components/Layout/ThemePreferenceProvider.razor
+++ b/src/HelpDesk.NewWeb/Components/Layout/ThemePreferenceProvider.razor
@@ -21,6 +21,7 @@
     private bool isDarkMode;
     private bool systemDarkMode;
     private bool initialized;
+    private long selectionVersion;
 
     public ThemePreferenceMode Mode => mode;
     public bool IsDarkMode => isDarkMode;
@@ -45,8 +46,16 @@
             return;
         }
 
-        mode = ParseMode(await JS.InvokeAsync<string?>("helpdeskThemePreference.get"));
-        systemDarkMode = await themeProvider.GetSystemDarkModeAsync();
+        var initializationVersion = selectionVersion;
+        var persistedMode = ParseMode(await JS.InvokeAsync<string?>("helpdeskThemePreference.get"));
+        var initialSystemDarkMode = await themeProvider.GetSystemDarkModeAsync();
+
+        if (initializationVersion == selectionVersion)
+        {
+            mode = persistedMode;
+        }
+
+        systemDarkMode = initialSystemDarkMode;
         isDarkMode = ResolveDarkMode();
         initialized = true;
 
@@ -57,6 +66,7 @@
 
     public async Task SetModeAsync(ThemePreferenceMode selectedMode)
     {
+        var updateVersion = ++selectionVersion;
         mode = selectedMode;
 
         if (mode is ThemePreferenceMode.System && themeProvider is not null)
@@ -64,6 +74,11 @@
             systemDarkMode = await themeProvider.GetSystemDarkModeAsync();
         }
 
+        if (updateVersion != selectionVersion)
+        {
+            return;
+        }
+
         isDarkMode = ResolveDarkMode();
         await JS.InvokeVoidAsync("helpdeskThemePreference.set", ToStorageValue(mode));
         await ApplyDocumentThemeAsync();
diff --git a/src/HelpDesk.NewWeb/Themes/RatelDeskPrepaintTheme.cs b/src/HelpDesk.NewWeb/Themes/RatelDeskPrepaintTheme.cs
new file mode 100644
index 00000000..53f23793
--- /dev/null
+++ b/src/HelpDesk.NewWeb/Themes/RatelDeskPrepaintTheme.cs
@@ -0,0 +1,106 @@
+using System.Globalization;
+using System.Text;
+using MudBlazor;
+using MudBlazor.Utilities;
+
+namespace HelpDesk.NewWeb.Themes;
+
+/// <summary>
+/// Emits the palette variables needed before the interactive MudBlazor provider can run.
+/// The values are read from <see cref="RatelDeskTheme"/>, which remains the sole palette source.
+/// </summary>
+public static class RatelDeskPrepaintTheme
+{
+    private static readonly RatelDeskTheme Theme = new();
+
+    public static string Css { get; } = BuildCss();
+
+    private static string BuildCss()
+    {
+        var css = new StringBuilder();
+        AppendPalette(css, "html[data-helpdesk-theme=\"light\"]", Theme.PaletteLight, "light");
+        AppendPalette(css, "html[data-helpdesk-theme=\"dark\"]", Theme.PaletteDark, "dark");
+
+        // JavaScript cannot read a stored override when it is disabled. System is the safe fallback.
+        css.Append("@media (prefers-color-scheme: dark){");
+        AppendPalette(css, "html:not([data-helpdesk-theme])", Theme.PaletteDark, "dark");
+        css.Append('}');
+        css.Append("@media (prefers-color-scheme: light){");
+        AppendPalette(css, "html:not([data-helpdesk-theme])", Theme.PaletteLight, "light");
+        css.Append('}');
+        return css.ToString();
+    }
+
+    private static void AppendPalette(StringBuilder css, string selector, Palette palette, string colorScheme)
+    {
+        css.Append(selector).Append("{color-scheme:").Append(colorScheme).Append(";background:").Append(Color(palette.Background)).Append(';');
+
+        AppendColor(css, "black", palette.Black);
+        AppendColor(css, "white", palette.White);
+        AppendColorFamily(css, "primary", palette.Primary, palette.PrimaryContrastText, palette.PrimaryDarken, palette.PrimaryLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "secondary", palette.Secondary, palette.SecondaryContrastText, palette.SecondaryDarken, palette.SecondaryLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "tertiary", palette.Tertiary, palette.TertiaryContrastText, palette.TertiaryDarken, palette.TertiaryLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "info", palette.Info, palette.InfoContrastText, palette.InfoDarken, palette.InfoLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "success", palette.Success, palette.SuccessContrastText, palette.SuccessDarken, palette.SuccessLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "warning", palette.Warning, palette.WarningContrastText, palette.WarningDarken, palette.WarningLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "error", palette.Error, palette.ErrorContrastText, palette.ErrorDarken, palette.ErrorLighten, palette.HoverOpacity);
+        AppendColorFamily(css, "dark", palette.Dark, palette.DarkContrastText, palette.DarkDarken, palette.DarkLighten, palette.HoverOpacity);
+
+        AppendColor(css, "text-primary", palette.TextPrimary, includeRgb: true);
+        AppendColor(css, "text-secondary", palette.TextSecondary, includeRgb: true);
+        AppendColor(css, "text-disabled", palette.TextDisabled, includeRgb: true);
+        AppendColor(css, "action-default", palette.ActionDefault);
+        Append(css, "action-default-hover", palette.ActionDefault.SetAlpha(palette.HoverOpacity).ToString(MudColorOutputFormats.RGBA));
+        AppendColor(css, "action-disabled", palette.ActionDisabled);
+        AppendColor(css, "action-disabled-background", palette.ActionDisabledBackground);
+        AppendColor(css, "surface", palette.Surface, includeRgb: true);
+        AppendColor(css, "background", palette.Background);
+        AppendColor(css, "background-gray", palette.BackgroundGray);
+        AppendColor(css, "drawer-background", palette.DrawerBackground);
+        AppendColor(css, "drawer-text", palette.DrawerText);
+        AppendColor(css, "drawer-icon", palette.DrawerIcon);
+        AppendColor(css, "appbar-background", palette.AppbarBackground);
+        AppendColor(css, "appbar-text", palette.AppbarText);
+        AppendColor(css, "lines-default", palette.LinesDefault);
+        AppendColor(css, "lines-inputs", palette.LinesInputs);
+        AppendColor(css, "table-lines", palette.TableLines);
+        AppendColor(css, "table-striped", palette.TableStriped);
+        AppendColor(css, "table-hover", palette.TableHover);
+        AppendColor(css, "divider", palette.Divider, includeRgb: true);
+        AppendColor(css, "divider-light", palette.DividerLight);
+        AppendColor(css, "skeleton", palette.Skeleton);
+        AppendColor(css, "gray-default", palette.GrayDefault);
+        AppendColor(css, "gray-light", palette.GrayLight);
+        AppendColor(css, "gray-lighter", palette.GrayLighter);
+        AppendColor(css, "gray-dark", palette.GrayDark);
+        AppendColor(css, "gray-darker", palette.GrayDarker);
+        AppendColor(css, "overlay-dark", palette.OverlayDark);
+        AppendColor(css, "overlay-light", palette.OverlayLight);
+        Append(css, "border-opacity", palette.BorderOpacity.ToString(CultureInfo.InvariantCulture));
+        css.Append("--mud-ripple-color:var(--mud-palette-text-primary);");
+        css.Append('}');
+    }
+
+    private static void AppendColorFamily(StringBuilder css, string name, MudColor color, MudColor contrast, string darken, string lighten, double hoverOpacity)
+    {
+        AppendColor(css, name, color, includeRgb: true);
+        AppendColor(css, $"{name}-text", contrast);
+        Append(css, $"{name}-darken", darken);
+        Append(css, $"{name}-lighten", lighten);
+        Append(css, $"{name}-hover", color.SetAlpha(hoverOpacity).ToString(MudColorOutputFormats.RGBA));
+    }
+
+    private static void AppendColor(StringBuilder css, string name, MudColor color, bool includeRgb = false)
+    {
+        Append(css, name, Color(color));
+        if (includeRgb)
+        {
+            Append(css, $"{name}-rgb", color.ToString(MudColorOutputFormats.ColorElements));
+        }
+    }
+
+    private static void Append(StringBuilder css, string name, string value) =>
+        css.Append("--mud-palette-").Append(name).Append(':').Append(value).Append(';');
+
+    private static string Color(MudColor color) => color.ToString(MudColorOutputFormats.RGBA);
+}
diff --git a/src/HelpDesk.NewWeb/wwwroot/js/theme-preference.js b/src/HelpDesk.NewWeb/wwwroot/js/theme-preference.js
deleted file mode 100644
index ff246cd8..00000000
--- a/src/HelpDesk.NewWeb/wwwroot/js/theme-preference.js
+++ /dev/null
@@ -1,20 +0,0 @@
-window.helpdeskThemePreference = (() => {
-    const storageKey = "helpdesk.theme.preference";
-
-    const apply = (isDarkMode) => {
-        document.documentElement.dataset.helpdeskTheme = isDarkMode ? "dark" : "light";
-    };
-
-    return {
-        get: () => window.localStorage.getItem(storageKey),
-        set: (value) => {
-            if (value === "system") {
-                window.localStorage.removeItem(storageKey);
-                return;
-            }
-
-            window.localStorage.setItem(storageKey, value);
-        },
-        apply
-    };
-})();
diff --git a/tests/Helpdesk.Tests/NewWeb/RatelDeskPrepaintThemeTests.cs b/tests/Helpdesk.Tests/NewWeb/RatelDeskPrepaintThemeTests.cs
new file mode 100644
index 00000000..2d2a9b86
--- /dev/null
+++ b/tests/Helpdesk.Tests/NewWeb/RatelDeskPrepaintThemeTests.cs
@@ -0,0 +1,41 @@
+extern alias NewWeb;
+
+using NewWeb::HelpDesk.NewWeb.Themes;
+using MudBlazor;
+using MudBlazor.Utilities;
+
+namespace Helpdesk.Tests.NewWeb;
+
+public sealed class RatelDeskPrepaintThemeTests
+{
+    [Fact]
+    public void Prepaint_css_uses_the_canonical_light_and_dark_palette_values()
+    {
+        var css = RatelDeskPrepaintTheme.Css;
+        var theme = new RatelDeskTheme();
+
+        Assert.Contains("html[data-helpdesk-theme=\"light\"]", css);
+        Assert.Contains($"--mud-palette-background:{Color(theme.PaletteLight.Background)};", css);
+        Assert.Contains($"--mud-palette-surface:{Color(theme.PaletteLight.Surface)};", css);
+        Assert.Contains($"--mud-palette-text-primary:{Color(theme.PaletteLight.TextPrimary)};", css);
+        Assert.Contains($"--mud-palette-appbar-background:{Color(theme.PaletteLight.AppbarBackground)};", css);
+        Assert.Contains($"--mud-palette-divider:{Color(theme.PaletteLight.Divider)};", css);
+
+        Assert.Contains("html[data-helpdesk-theme=\"dark\"]", css);
+        Assert.Contains($"--mud-palette-background:{Color(theme.PaletteDark.Background)};", css);
+        Assert.Contains($"--mud-palette-surface:{Color(theme.PaletteDark.Surface)};", css);
+        Assert.Contains($"--mud-palette-text-primary:{Color(theme.PaletteDark.TextPrimary)};", css);
+        Assert.Contains($"--mud-palette-appbar-background:{Color(theme.PaletteDark.AppbarBackground)};", css);
+        Assert.Contains($"--mud-palette-divider:{Color(theme.PaletteDark.Divider)};", css);
+        Assert.Contains($"--mud-palette-overlay-dark:{Color(theme.PaletteDark.OverlayDark)};", css);
+    }
+
+    [Fact]
+    public void Prepaint_css_has_a_system_fallback_when_javascript_is_unavailable()
+    {
+        Assert.Contains("@media (prefers-color-scheme: dark){html:not([data-helpdesk-theme])", RatelDeskPrepaintTheme.Css);
+        Assert.Contains("@media (prefers-color-scheme: light){html:not([data-helpdesk-theme])", RatelDeskPrepaintTheme.Css);
+    }
+
+    private static string Color(MudColor color) => color.ToString(MudColorOutputFormats.RGBA);
+}
diff --git a/tests/ux/theme-first-paint.spec.ts b/tests/ux/theme-first-paint.spec.ts
new file mode 100644
index 00000000..6c550231
--- /dev/null
+++ b/tests/ux/theme-first-paint.spec.ts
@@ -0,0 +1,105 @@
+import { expect, test } from '@playwright/test';
+
+type ThemeCase = {
+  colorScheme: 'dark' | 'light';
+  expected: 'dark' | 'light';
+  preference: string;
+  colors: { background: string; surface: string; text: string };
+};
+
+const cases: ThemeCase[] = [
+  {
+    colorScheme: 'dark',
+    expected: 'dark',
+    preference: ' system ',
+    colors: { background: 'rgb(12, 15, 19)', surface: 'rgb(23, 28, 35)', text: 'rgb(237, 241, 245)' }
+  },
+  {
+    colorScheme: 'light',
+    expected: 'dark',
+    preference: ' DARK ',
+    colors: { background: 'rgb(12, 15, 19)', surface: 'rgb(23, 28, 35)', text: 'rgb(237, 241, 245)' }
+  },
+  {
+    colorScheme: 'dark',
+    expected: 'light',
+    preference: ' light ',
+    colors: { background: 'rgb(245, 247, 250)', surface: 'rgb(255, 255, 255)', text: 'rgb(21, 34, 51)' }
+  }
+];
+
+for (const themeCase of cases) {
+  test(`keeps the ${themeCase.expected} palette through a paused runtime (${themeCase.preference.trim()})`, async ({ browser }) => {
+    const context = await browser.newContext({
+      colorScheme: themeCase.colorScheme,
+      ignoreHTTPSErrors: process.env.HELPDESK_E2E_IGNORE_HTTPS_ERRORS === 'true'
+    });
+    let releaseRuntime: (() => void) | undefined;
+    const runtimeRelease = new Promise<void>((resolve) => { releaseRuntime = resolve; });
+
+    await context.addInitScript((preference) => {
+      localStorage.setItem('helpdesk.theme.preference', preference);
+      const samples: Array<{ theme: string | undefined; colorScheme: string; background: string; surface: string; text: string }> = [];
+      let observing = true;
+      const capture = () => {
+        const portal = document.querySelector<HTMLElement>('.helpdesk-portal-page');
+        const card = document.querySelector<HTMLElement>('.helpdesk-portal-action');
+        const heading = document.querySelector<HTMLElement>('h1');
+        if (portal && card && heading && portal.getBoundingClientRect().height > 0) {
+          samples.push({
+            theme: document.documentElement.dataset.helpdeskTheme,
+            colorScheme: getComputedStyle(document.documentElement).colorScheme,
+            background: getComputedStyle(document.body).backgroundColor,
+            surface: getComputedStyle(card).backgroundColor,
+            text: getComputedStyle(heading).color
+          });
+        }
+
+        if (observing) requestAnimationFrame(capture);
+      };
+
+      requestAnimationFrame(capture);
+      (window as typeof window & { __helpdeskThemeFirstPaint?: { samples: typeof samples; stop: () => void } }).__helpdeskThemeFirstPaint = {
+        samples,
+        stop: () => { observing = false; }
+      };
+    }, themeCase.preference);
+    await context.route('**/_framework/blazor.web.js', async (route) => {
+      await runtimeRelease;
+      await route.continue();
+    });
+
+    const page = await context.newPage();
+    try {
+      await page.goto('/', { waitUntil: 'commit' });
+      await page.waitForFunction(() => document.querySelector('.helpdesk-portal-action')?.getBoundingClientRect().height);
+      await page.waitForFunction(() =>
+        (window as typeof window & { __helpdeskThemeFirstPaint: { samples: unknown[] } }).__helpdeskThemeFirstPaint.samples.length > 0);
+
+      const pausedSamples = await page.evaluate(() =>
+        (window as typeof window & { __helpdeskThemeFirstPaint: { samples: unknown[] } }).__helpdeskThemeFirstPaint.samples);
+      expect(pausedSamples, 'the paused runtime must leave visible prerendered content to observe').not.toHaveLength(0);
+      expect(pausedSamples).toEqual(expect.arrayContaining([
+        expect.objectContaining({ theme: themeCase.expected, colorScheme: themeCase.expected, ...themeCase.colors })
+      ]));
+
+      releaseRuntime!();
+      await page.waitForLoadState('domcontentloaded');
+      await expect(page.locator('html')).toHaveAttribute('data-helpdesk-theme', themeCase.expected);
+      await expect.poll(() => page.evaluate(() => {
+        const card = document.querySelector<HTMLElement>('.helpdesk-portal-action')!;
+        const heading = document.querySelector<HTMLElement>('h1')!;
+        return {
+          background: getComputedStyle(document.body).backgroundColor,
+          surface: getComputedStyle(card).backgroundColor,
+          text: getComputedStyle(heading).color
+        };
+      })).toEqual(themeCase.colors);
+    } finally {
+      releaseRuntime?.();
+      await page.evaluate(() =>
+        (window as typeof window & { __helpdeskThemeFirstPaint?: { stop: () => void } }).__helpdeskThemeFirstPaint?.stop()).catch(() => undefined);
+      await context.close();
+    }
+  });
+}
