From 531f901096ffdcbadee19009f1cb0fa7ddba9322 Mon Sep 17 00:00:00 2001
From: RyansGit <ryan@refari.co>
Date: Fri, 15 May 2026 22:33:08 +0100
Subject: [PATCH] fix(admin): prevent dark-mode flash on light-preference
 systems

If a user has set the LiteSpeed admin to light mode but their OS prefers dark,
the page briefly flashed dark before the JS toggle ran. The light preference
is now mirrored to a cookie so PHP can stamp the correct mode class on the
body server-side and the right theme paints on first load.
---
 assets/js/litespeed-cache-admin.js | 17 ++++++++++++++++-
 src/admin-display.cls.php          |  8 ++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/assets/js/litespeed-cache-admin.js b/assets/js/litespeed-cache-admin.js
index bc8532577..13233d3ee 100644
--- a/assets/js/litespeed-cache-admin.js
+++ b/assets/js/litespeed-cache-admin.js
@@ -302,6 +302,18 @@ function litespeed_init_dark_mode() {
 	// Only add toggle on LiteSpeed pages
 	if (window.location.search.indexOf('page=litespeed') === -1) return;
 
+	// Mirror the saved preference into a cookie so PHP can stamp the body class
+	// on first paint (prevents the dark flash when localStorage says "light").
+	function litespeed_set_dark_cookie(value) {
+		var base = 'litespeed-dark-preference=' + (value || '') + '; path=/; SameSite=Lax';
+		document.cookie = base + '; max-age=' + (value ? 31536000 : 0);
+	}
+	// Back-fill the cookie for existing users whose preference is still localStorage-only.
+	var _savedPref = localStorage.getItem('litespeed-dark-preference');
+	if (_savedPref && document.cookie.indexOf('litespeed-dark-preference=') === -1) {
+		litespeed_set_dark_cookie(_savedPref);
+	}
+
 	// Create toggle button
 	var toggleBtn = document.createElement('button');
 	toggleBtn.className = 'litespeed-dark-mode-toggle';
@@ -351,8 +363,11 @@ function litespeed_init_dark_mode() {
 		// Toggle and store only if different from browser preference
 		if (!currentlyDark === prefersDark) {
 			localStorage.removeItem('litespeed-dark-preference');
+			litespeed_set_dark_cookie('');
 		} else {
-			localStorage.setItem('litespeed-dark-preference', currentlyDark ? 'light' : 'dark');
+			var newPref = currentlyDark ? 'light' : 'dark';
+			localStorage.setItem('litespeed-dark-preference', newPref);
+			litespeed_set_dark_cookie(newPref);
 		}
 
 		applyDarkMode();
diff --git a/src/admin-display.cls.php b/src/admin-display.cls.php
index 5fcf883bf..895a7dc9b 100644
--- a/src/admin-display.cls.php
+++ b/src/admin-display.cls.php
@@ -337,6 +337,14 @@ function ( $footer_text ) {
 				if ( $screen && in_array( $screen->id, [ 'settings_page_litespeed-cache-options', 'toplevel_page_litespeed' ], true ) ) {
 					$classes .= ' litespeed-cache_page_litespeed';
 				}
+				// Stamp the dark/light override server-side from the cookie set by admin JS,
+				// so the stylesheet picks the right mode on first paint (no FOUC).
+				if ( ! empty( $_COOKIE['litespeed-dark-preference'] ) ) {
+					$pref = sanitize_key( wp_unslash( $_COOKIE['litespeed-dark-preference'] ) );
+					if ( 'dark' === $pref || 'light' === $pref ) {
+						$classes .= ' litespeed-' . $pref . 'mode';
+					}
+				}
 				return $classes;
 			} );
 		} );