Re-evaluate @media when the system colour scheme changes

The adapters already invalidated their cached theme on a system preference
change, but nothing acted on it: the cascade is only re-evaluated during layout,
and an idle window never lays out - so switching Windows between light and dark
left prefers-color-scheme rules stuck at whatever was true when the document
loaded.

RAdapter gains a ColorSchemeChanged event. HtmlContainerInt subscribes and asks
the host to lay out and repaint, which runs the existing viewport check and
re-cascades if the outcome moved. The event only reports a real change: the
WinForms and WPF adapters re-read the theme and compare, since the General
preference category covers much more than the theme and would otherwise force a
re-cascade on every unrelated setting change.

The handler is detached on dispose - the adapter is a process-wide singleton and
would otherwise keep every container that ever rendered alive.

The re-cascade itself stays in PerformLayout rather than the event handler,
because SystemEvents can raise on a thread other than the host's.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 2 people

Source/HtmlRenderer.WPF/Adapters/WpfAdapter.cs

@@ -74,8 +74,15 @@ private WpfAdapter()
 
             SystemEvents.UserPreferenceChanged += (sender, e) =>
             {
-                if (e.Category == UserPreferenceCategory.General)
-                    _colorScheme = null;
+                if (e.Category != UserPreferenceCategory.General) return;
+
+                // The General category covers far more than the theme, so re-read and only report a
+                // change if the scheme really moved - otherwise every unrelated preference change
+                // would force a re-cascade and repaint.
+                var previous = _colorScheme;
+                _colorScheme = null;
+                if (previous.HasValue && previous.Value != SystemColorScheme)
+                    OnColorSchemeChanged();
             };
         }
 

Source/HtmlRenderer.WinForms/Adapters/WinFormsAdapter.cs

@@ -51,8 +51,15 @@ private WinFormsAdapter()
 
             Microsoft.Win32.SystemEvents.UserPreferenceChanged += (sender, e) =>
             {
-                if (e.Category == Microsoft.Win32.UserPreferenceCategory.General)
-                    _colorScheme = null;
+                if (e.Category != Microsoft.Win32.UserPreferenceCategory.General) return;
+
+                // The General category covers far more than the theme, so re-read and only report a
+                // change if the scheme really moved - otherwise every unrelated preference change
+                // would force a re-cascade and repaint.
+                var previous = _colorScheme;
+                _colorScheme = null;
+                if (previous.HasValue && previous.Value != SystemColorScheme)
+                    OnColorSchemeChanged();
             };
         }
 

Source/HtmlRenderer/Adapters/RAdapter.cs

@@ -92,13 +92,35 @@ public virtual string DefaultMediaType
         /// <summary>
         /// The colour scheme the rendering surface presents, answering the <c>prefers-color-scheme</c>
         /// media feature. Defaults to <see cref="RColorScheme.Light"/>; an adapter that renders onto a
-        /// themed surface should report the system setting instead.
+        /// themed surface should report the system setting instead, and raise
+        /// <see cref="ColorSchemeChanged"/> when it changes.
         /// </summary>
         public virtual RColorScheme SystemColorScheme
         {
             get { return RColorScheme.Light; }
         }
 
+        /// <summary>
+        /// Raised when <see cref="SystemColorScheme"/> has changed, so anything rendered against it can
+        /// re-evaluate its <c>prefers-color-scheme</c> rules and repaint. Never raised by an adapter
+        /// whose scheme is fixed.
+        /// </summary>
+        /// <remarks>
+        /// Handlers are held for the lifetime of the adapter, which is typically a process-wide
+        /// singleton, so a subscriber must unsubscribe when it is disposed.
+        /// </remarks>
+        public event EventHandler ColorSchemeChanged;
+
+        /// <summary>
+        /// Raises <see cref="ColorSchemeChanged"/>. For adapters that track a system theme.
+        /// </summary>
+        protected void OnColorSchemeChanged()
+        {
+            var handler = ColorSchemeChanged;
+            if (handler != null)
+                handler(this, EventArgs.Empty);
+        }
+
         /// <summary>
         /// Get the default CSS stylesheet data.
         /// </summary>

Source/HtmlRenderer/Core/HtmlContainerInt.cs

@@ -224,6 +224,30 @@ public HtmlContainerInt(RAdapter adapter)
 
             _adapter = adapter;
             _cssParser = new CssParser(adapter);
+
+            // A system theme change alters what prefers-color-scheme reports, which can change which
+            // rules apply. Nothing else would notice: the cascade is only re-evaluated during layout,
+            // and an idle window does not lay out.
+            _colorSchemeChangedHandler = (sender, e) => OnAdapterColorSchemeChanged();
+            _adapter.ColorSchemeChanged += _colorSchemeChangedHandler;
+        }
+
+        /// <summary>
+        /// Kept so the handler can be detached from the adapter - which is typically a process-wide
+        /// singleton, and would otherwise keep every container that ever rendered alive.
+        /// </summary>
+        private readonly EventHandler _colorSchemeChangedHandler;
+
+        /// <summary>
+        /// The colour scheme changed, so ask the host to lay out and repaint. The re-cascade itself
+        /// happens in <see cref="PerformLayout"/>, on the host's own thread - this event can arrive on
+        /// another one.
+        /// </summary>
+        private void OnAdapterColorSchemeChanged()
+        {
+            if (_root == null) return;
+
+            RequestRefresh(true);
         }
 
         /// <summary>
@@ -1081,6 +1105,8 @@ private void Dispose(bool all)
                     ImageLoad = null;
                 }
 
+                _adapter.ColorSchemeChanged -= _colorSchemeChangedHandler;
+
                 _cssData = null;
                 if (_root != null)
                     _root.Dispose();