Fix transparency reassertion on shell events

Author: Mirochill

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-05-30
+
+### Fixed
+
+- Reassert the transparent accent and wallpaper-backing Z-order immediately
+  when Explorer application buttons or the foreground window change, then
+  once more after a short settling interval.
+- Keep the wallpaper-only taskbar background available when the Windows key
+  opens shell UI from a foreground fullscreen application.
+
+### Changed
+
+- Distinguish foreground-location notifications from real foreground changes
+  so ordinary window movements still update fullscreen state without
+  repeatedly reapplying the taskbar style.
+
 ## [1.0.0] - 2026-05-30
 
 ### Added
@@ -22,5 +38,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   restoration scripts.
 - Regression tests, Windows CI, public documentation, and community files.
 
-[Unreleased]: https://github.com/Mirochill/MiniTaskbar/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/Mirochill/MiniTaskbar/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/Mirochill/MiniTaskbar/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/Mirochill/MiniTaskbar/releases/tag/v1.0.0

README.md

@@ -93,10 +93,17 @@ or moved and automatically rearms itself after an Explorer restart. When the
 button geometry changes, the group slides to its new center with a
 `180 ms` cubic ease-out transition.
 
-MiniTaskbar also watches foreground-window and geometry changes. When the
-active window covers its complete monitor, the wallpaper backing is hidden
-immediately so games and videos receive an unobstructed fullscreen surface.
-It is restored as soon as fullscreen ends.
+Relevant Explorer and foreground-window changes also reassert the transparent
+accent and wallpaper-backing Z-order immediately, then once more after a short
+settling interval. This keeps the wallpaper-only background intact when an
+application opens without doing extra style work for ordinary window
+movements.
+
+When the active window covers its complete monitor, the wallpaper backing is
+hidden immediately so games and videos receive an unobstructed fullscreen
+surface. Pressing the Windows key makes the backing available again while the
+shell UI is visible, and returning to the fullscreen application hides it
+again immediately.
 
 ## Build And Test
 

docs/PERFORMANCE.md

@@ -1,7 +1,7 @@
 # Performance
 
 MiniTaskbar is designed to remain quiet while idle and to avoid desktop frame
-capture. This page documents the measurements collected for version `1.0.0`.
+capture. This page documents the measurements collected for version `1.0.1`.
 
 ## Design Principles
 
@@ -11,6 +11,9 @@ capture. This page documents the measurements collected for version `1.0.0`.
   application-button changes.
 - Accessibility state-only notifications are ignored because they do not
   change button geometry.
+- Application-button and real foreground changes reassert taskbar
+  transparency immediately, then once more after a short settling interval.
+  Foreground-location changes do not perform that extra style work.
 - Animation advances at approximately `60 fps` only while the application
   button group is moving.
 - Inexpensive fallback checks recover from Explorer changes without a busy
@@ -31,10 +34,10 @@ machine.
 
 ```text
 IdleSampleSeconds      : 60
-CpuPercentOfOneCore    : 0.547
-WorkingSetMiB          : 24.70
-PrivateMemoryMiB       : 22.53
-Handles                : 218
+CpuPercentOfOneCore    : 0.417
+WorkingSetMiB          : 25.18
+PrivateMemoryMiB       : 23.69
+Handles                : 219
 Threads                : 5
 BuiltExecutableBytes   : 24064
 ```
@@ -47,19 +50,22 @@ Focused probes also exercised the user-visible paths:
 TaskbarOverlayRect              : [0,1040,1920,1080]
 WallpaperSource                 : WorkerW
 CenteredApplicationGroupDeltaPx : 0
-FullscreenBackingHiddenMs       : 24
-FullscreenSurfaceClearMs        : 30
-FullscreenExitReshowMs          : 0
-AccentRecoveryMs                : 4703
+FullscreenWinKeyBackingShownMs  : <=47
+FullscreenWinKeyWallpaperMs     : <=408
+FullscreenReturnBackingHiddenMs : <=29
+AppOpenAccentRecoveryMs         : <=40
+FallbackAccentCadenceMs         : 5000
 IconOpenFirstMoveDeltaPx        : 23
 PurpleFallbackObserved          : false
 UnderlyingWindowVisible         : false
 ```
 
-The fullscreen probe used a true foreground fullscreen window. The accent
-recovery probe deliberately forced a colored taskbar state and measured the
-resident's periodic recovery. The icon probe added and removed an application
-button and observed the centered slide.
+The fullscreen probe used a true foreground fullscreen window, deliberately
+forced a purple taskbar state, pressed the Windows key, and returned to the
+fullscreen application. A separate probe forced the same purple state before
+opening an application and observed event-driven recovery before its first
+usable `40 ms` sample. The icon probe added and removed an application button
+and observed the centered slide.
 
 ## Interpretation
 

src/Program.cs

@@ -158,13 +158,14 @@ internal static int Run(int waitMilliseconds)
                 var lastShellPoll = Stopwatch.StartNew();
                 var lastCenterFallback = Stopwatch.StartNew();
                 var eventSettle = new Stopwatch();
+                var transparencySettle = new Stopwatch();
 
                 using (var backdrops = new WallpaperBackdropManager())
                 using (var events = new TaskbarEventWatcher(previous))
                 {
                     bool fullscreen = FullscreenState.IsForegroundFullscreen();
                     backdrops.SetVisible(!fullscreen);
-                    if (!backdrops.Refresh(previous, true)
+                    if (!backdrops.Refresh(previous, true, true)
                         || !TaskbarCenter.CenterImmediately(previous))
                     {
                         return 3;
@@ -177,7 +178,11 @@ internal static int Run(int waitMilliseconds)
                         {
                             bool settling = eventSettle.IsRunning
                                 && eventSettle.ElapsedMilliseconds < EventSettleMilliseconds;
-                            int loopWaitMilliseconds = TaskbarCenter.HasActiveAnimation || settling
+                            bool transparencySettling = transparencySettle.IsRunning
+                                && transparencySettle.ElapsedMilliseconds < EventSettleMilliseconds;
+                            int loopWaitMilliseconds = TaskbarCenter.HasActiveAnimation
+                                || settling
+                                || transparencySettling
                                 ? AnimationFrameMilliseconds
                                 : PollMilliseconds;
                             TaskbarEventKind eventKind = events.Wait(loopWaitMilliseconds);
@@ -187,13 +192,31 @@ internal static int Run(int waitMilliseconds)
                                 eventSettle.Restart();
                             }
 
+                            bool transparencyEvent = IsTransparencyReassertEvent(eventKind);
+                            if (transparencyEvent)
+                            {
+                                transparencySettle.Restart();
+                            }
+
                             bool currentFullscreen = FullscreenState.IsForegroundFullscreen();
-                            if (fullscreen != currentFullscreen)
+                            bool fullscreenChanged = fullscreen != currentFullscreen;
+                            if (fullscreenChanged)
                             {
                                 fullscreen = currentFullscreen;
                                 backdrops.SetVisible(!fullscreen);
+                            }
+
+                            bool transparencySettleDue = transparencySettle.IsRunning
+                                && transparencySettle.ElapsedMilliseconds >= EventSettleMilliseconds;
+                            if (fullscreenChanged || transparencyEvent || transparencySettleDue)
+                            {
                                 TaskbarAccent.Apply(current, AccentState.EnableTransparentGradient);
+                                backdrops.Refresh(current, false, true);
                                 lastApplied.Restart();
+                                if (transparencySettleDue)
+                                {
+                                    transparencySettle.Reset();
+                                }
                             }
 
                             bool taskbarsChanged = false;
@@ -217,7 +240,10 @@ internal static int Run(int waitMilliseconds)
 
                                 bool refreshSource =
                                     lastSourceRefresh.ElapsedMilliseconds >= SourceRefreshMilliseconds;
-                                backdrops.Refresh(current, refreshSource);
+                                backdrops.Refresh(
+                                    current,
+                                    refreshSource,
+                                    taskbarsChanged || refreshSource);
                                 if (refreshSource)
                                 {
                                     lastSourceRefresh.Restart();
@@ -277,19 +303,27 @@ internal static bool HaveSameHandles(IList<IntPtr> left, IList<IntPtr> right)
 
             return true;
         }
+
+        internal static bool IsTransparencyReassertEvent(TaskbarEventKind eventKind)
+        {
+            return eventKind == TaskbarEventKind.Centering
+                || eventKind == TaskbarEventKind.Foreground;
+        }
     }
 
     internal enum TaskbarEventKind
     {
         None,
         Centering,
-        Foreground
+        Foreground,
+        ForegroundLocation
     }
 
     internal sealed class TaskbarEventWatcher : IDisposable
     {
         private readonly AutoResetEvent _centeringChanged = new AutoResetEvent(false);
         private readonly AutoResetEvent _foregroundChanged = new AutoResetEvent(false);
+        private readonly AutoResetEvent _foregroundLocationChanged = new AutoResetEvent(false);
         private readonly WaitHandle[] _waitHandles;
         private readonly ManualResetEvent _ready = new ManualResetEvent(false);
         private readonly NativeMethods.WinEventProc _callback;
@@ -306,7 +340,12 @@ internal sealed class TaskbarEventWatcher : IDisposable
         internal TaskbarEventWatcher(IList<IntPtr> taskbars)
         {
             _callback = OnWinEvent;
-            _waitHandles = new WaitHandle[] { _centeringChanged, _foregroundChanged };
+            _waitHandles = new WaitHandle[]
+            {
+                _centeringChanged,
+                _foregroundChanged,
+                _foregroundLocationChanged
+            };
             Refresh(taskbars);
             _thread = new Thread(RunMessageLoop)
             {
@@ -325,8 +364,13 @@ internal TaskbarEventKind Wait(int milliseconds)
                 return TaskbarEventKind.Centering;
             }
 
-            return result == 1
-                ? TaskbarEventKind.Foreground
+            if (result == 1)
+            {
+                return TaskbarEventKind.Foreground;
+            }
+
+            return result == 2
+                ? TaskbarEventKind.ForegroundLocation
                 : TaskbarEventKind.None;
         }
 
@@ -375,6 +419,7 @@ public void Dispose()
             _thread.Join(5000);
             _centeringChanged.Dispose();
             _foregroundChanged.Dispose();
+            _foregroundLocationChanged.Dispose();
             _ready.Dispose();
         }
 
@@ -481,7 +526,7 @@ private void OnWinEvent(
             if (eventType == NativeMethods.EventObjectLocationChange
                 && window == _foregroundWindow)
             {
-                _foregroundChanged.Set();
+                _foregroundLocationChanged.Set();
             }
 
             if (IsCenteringEvent(eventType) && _windows.Contains(window))
@@ -576,7 +621,7 @@ internal sealed class WallpaperBackdropManager : IDisposable
         private IntPtr _source;
         private bool _visible = true;
 
-        internal bool Refresh(IList<IntPtr> taskbars, bool refreshSource)
+        internal bool Refresh(IList<IntPtr> taskbars, bool refreshSource, bool reassert)
         {
             var activeTaskbars = new HashSet<IntPtr>(taskbars);
             var removed = new List<IntPtr>();
@@ -615,7 +660,7 @@ internal bool Refresh(IList<IntPtr> taskbars, bool refreshSource)
                     _backdrops.Add(taskbar, backdrop);
                 }
 
-                success = backdrop.Refresh(_source, refreshSource, _visible) && success;
+                success = backdrop.Refresh(_source, reassert, _visible) && success;
             }
 
             return success;

tests/MiniTaskbar.Tests.cs

@@ -31,6 +31,7 @@ private static int Main(string[] args)
             Run("Transparent accent avoids zero-color fallback", TestTransparentAccentColor);
             Run("Slide interpolation", TestSlideInterpolation);
             Run("WinEvent centering filter", TestWinEventCenteringFilter);
+            Run("Transparency reassert event filter", TestTransparencyReassertEventFilter);
             Run("Fullscreen monitor coverage", TestFullscreenMonitorCoverage);
             Run("Transparent accent recovery cadence", TestTransparentAccentRecoveryCadence);
 
@@ -190,6 +191,22 @@ private static void TestFullscreenMonitorCoverage()
                 "A regular maximized window should not be treated as fullscreen.");
         }
 
+        private static void TestTransparencyReassertEventFilter()
+        {
+            AssertTrue(
+                ResidentTaskbar.IsTransparencyReassertEvent(TaskbarEventKind.Centering),
+                "Application-button changes should reassert transparency.");
+            AssertTrue(
+                ResidentTaskbar.IsTransparencyReassertEvent(TaskbarEventKind.Foreground),
+                "Foreground changes should reassert transparency.");
+            AssertFalse(
+                ResidentTaskbar.IsTransparencyReassertEvent(TaskbarEventKind.ForegroundLocation),
+                "Window movement should not repeatedly reassert transparency.");
+            AssertFalse(
+                ResidentTaskbar.IsTransparencyReassertEvent(TaskbarEventKind.None),
+                "A timeout should not reassert transparency.");
+        }
+
         private static void TestTransparentAccentRecoveryCadence()
         {
             AssertEqual(5000, ResidentTaskbar.PeriodicReapplyMilliseconds);