Add screenshots and foreground hook for flyout

Add screenshot assets and galleries to README and docs (CSS and HTML) with a CSS lightbox; tweak README wording. Introduce Win32 foreground APIs and a global EVENT_SYSTEM_FOREGROUND hook in Win32Helper (GetForegroundWindow, SetForegroundWindow, SetWinEventHook, UnhookWinEvent). Update TrayFlyout to use the window handle, set foreground when showing, install/uninstall the foreground-change hook, and ignore immediate foreground events via a short grace period so the flyout doesn't self-dismiss right after being shown. Misc: apply window chrome/ DPI fixes and ensure proper resource cleanup.

Author: Sammeeeeeeee

README.md

@@ -19,16 +19,30 @@
 
 A Windows 11 native eye-break reminder. 
 
+<p align="center">
+  <a href="docs/screenshots/flyout-countdown.png"><img src="docs/screenshots/flyout-countdown.png" width="180" alt="Flyout: countdown"></a>
+  <a href="docs/screenshots/flyout-snoozed.png"><img src="docs/screenshots/flyout-snoozed.png" width="180" alt="Flyout: snoozed"></a>
+  <a href="docs/screenshots/short-break-popup.png"><img src="docs/screenshots/short-break-popup.png" width="180" alt="Short break popup"></a>
+  <a href="docs/screenshots/short-break-countdown.png"><img src="docs/screenshots/short-break-countdown.png" width="180" alt="Short break: countdown"></a>
+  <a href="docs/screenshots/long-break-popup.png"><img src="docs/screenshots/long-break-popup.png" width="180" alt="Long break popup"></a>
+</p>
+
+<sub align="center"><i>Click any screenshot to enlarge.</i></sub>
+
+
 ## What is the 20/20/20 rule?
 
 The 20/20/20 rule is a [proven technique](https://pubmed.ncbi.nlm.nih.gov/36473088/) to prevent eye strain, dryness and degradation. 
 
 ## Twenti
 
 Built with **WinUI 3** (Windows App SDK), this aims to be native and light, to be as unobtrusive as possible, but easily accessible. 
-It lives in the tray, with the minutes left as countdown. A flyout on click shows more information. Every 20 minutes, a pop up appears in the centre of your screen. You can choose to delay, or press enter to start the countdown (optional: accompanied by white noise). Every 3rd pop up is for 2 minutes. 
 
-### Keyboard (while the popup is focused)
+It lives in the tray, with the minutes left as countdown. 
+A flyout on click shows more information. Every 20 minutes, a pop up appears in the centre of your screen. 
+You can choose to delay, or press enter to start the countdown (optional: accompanied by white noise). Every 3rd pop up is for 2 minutes. 
+
+### Keyboard
 
 - `Enter` — start the break timer
 - `Esc` — snooze 5 minutes
@@ -38,8 +52,9 @@ It lives in the tray, with the minutes left as countdown. A flyout on click show
 
 Snooze 5 / 15 / 30 minutes · Mute or Unmute sounds 
 
-### Sounds (mutable)
+### Sounds 
 
+Mutable through the context menue (right click tray icon)
 - Soft 1318 Hz pre-ping 5 seconds before
 - Warm 3-note chime when the popup appears
 - Brown-noise water ambient during the break
@@ -61,15 +76,14 @@ dotnet build
 dotnet run
 ```
 
-The app starts straight into the system tray.
 
 ## Build a portable single-file exe
 
 ```pwsh
 dotnet publish -c Release -r win-x64 -o publish
 ```
 
-Output: `publish\Twenti.exe`. The Windows App SDK runtime is bundled.
+Output: `publish\Twenti.exe`. Windows App SDK runtime is bundled.
 
 ## Build the installer
 
@@ -78,4 +92,4 @@ dotnet publish -c Release -r win-x64 -o publish
 & "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe" installer\Twenti.iss
 ```
 
-Output: `installer\Output\Twenti-Setup.exe`. Installs as user or system wide. Adds a Start Menu entry, optionally runs at login.
+Output: `installer\Output\Twenti-Setup.exe`. Installs as user or system wide, adds a Start Menu entry, optionally runs at login.

Services/Win32Helper.cs

@@ -91,6 +91,27 @@ public static void HideFromAltTab(IntPtr hwnd)
         SetWindowLongPtr(hwnd, GWL_EXSTYLE, new IntPtr(ex | WS_EX_TOOLWINDOW));
     }
 
+    [DllImport("user32.dll")]
+    public static extern IntPtr GetForegroundWindow();
+
+    [DllImport("user32.dll")]
+    public static extern bool SetForegroundWindow(IntPtr hwnd);
+
+    // ── Global foreground-change hook ──────────────────────────────────────
+    public delegate void WinEventCallback(IntPtr hWinEventHook, uint eventType,
+        IntPtr hwnd, int idObject, int idChild, uint dwEventThread, uint dwmsEventTime);
+
+    public const uint EVENT_SYSTEM_FOREGROUND = 0x0003;
+    public const uint WINEVENT_OUTOFCONTEXT  = 0x0000;
+
+    [DllImport("user32.dll")]
+    public static extern IntPtr SetWinEventHook(uint eventMin, uint eventMax,
+        IntPtr hmodWinEventProc, WinEventCallback lpfnWinEventProc,
+        uint idProcess, uint idThread, uint dwFlags);
+
+    [DllImport("user32.dll")]
+    public static extern bool UnhookWinEvent(IntPtr hWinEventHook);
+
     [StructLayout(LayoutKind.Sequential)]
     private struct POINT { public int X; public int Y; }
 

Views/TrayFlyout.xaml.cs

@@ -1,6 +1,7 @@
 using System;
 using System.ComponentModel;
 using Microsoft.UI;
+using Microsoft.UI.Dispatching;
 using Microsoft.UI.Windowing;
 using Microsoft.UI.Xaml;
 using Microsoft.UI.Xaml.Media;
@@ -14,9 +15,20 @@ public sealed partial class TrayFlyout : Window
 {
     private readonly BreakStateMachine _sm;
     private AppWindow? _appWindow;
+    private IntPtr _hwnd;
     private double _scale = 1.0;
     private bool _isVisible;
 
+    // Foreground-change hook. We keep a strong reference to the delegate so the
+    // GC doesn't reclaim it while the OS still has the function pointer.
+    private IntPtr _hook = IntPtr.Zero;
+    private Win32Helper.WinEventCallback? _hookProc;
+
+    // Brief grace period right after Show() — Windows may not have made us the
+    // foreground window yet, and we don't want to immediately self-dismiss.
+    private DateTime _shownAt;
+    private static readonly TimeSpan GracePeriod = TimeSpan.FromMilliseconds(250);
+
     public TrayFlyout()
     {
         InitializeComponent();
@@ -28,53 +40,44 @@ public TrayFlyout()
         ConfigureChromeOnce();
 
         _sm.PropertyChanged += OnStateChanged;
-        Activated += OnActivated;
 
         UpdateUi();
-
-        // Stay hidden until first ShowFlyout(). Avoids the window flashing on app start.
         _appWindow?.Hide();
     }
 
     private void ConfigureChromeOnce()
     {
-        var hwnd = WindowNative.GetWindowHandle(this);
-        var id = Win32Interop.GetWindowIdFromWindow(hwnd);
+        _hwnd = WindowNative.GetWindowHandle(this);
+        var id = Win32Interop.GetWindowIdFromWindow(_hwnd);
         _appWindow = AppWindow.GetFromWindowId(id);
 
         if (_appWindow.Presenter is OverlappedPresenter p)
         {
             p.IsMaximizable = false;
             p.IsMinimizable = false;
             p.IsResizable = false;
-            // IsAlwaysOnTop must be true so the flyout always lands above the
-            // window the user clicked from. Click-away is handled via the
-            // Activated event — it still fires for topmost windows.
+            // Topmost so it draws above the user's app windows when shown.
+            // The foreground-change hook below handles dismissal.
             p.IsAlwaysOnTop = true;
             p.SetBorderAndTitleBar(false, false);
         }
 
         _appWindow.IsShownInSwitchers = false;
-        Win32Helper.HideFromAltTab(hwnd);
-        Win32Helper.MakeBorderless(hwnd);
-        Win32Helper.ForceImmersiveDark(hwnd);
-        Win32Helper.RoundCorners(hwnd);
-        Win32Helper.RemoveBorder(hwnd);
+        Win32Helper.HideFromAltTab(_hwnd);
+        Win32Helper.MakeBorderless(_hwnd);
+        Win32Helper.ForceImmersiveDark(_hwnd);
+        Win32Helper.RoundCorners(_hwnd);
+        Win32Helper.RemoveBorder(_hwnd);
 
-        _scale = Win32Helper.GetDpiScale(hwnd);
+        _scale = Win32Helper.GetDpiScale(_hwnd);
     }
 
-    /// <summary>
-    /// Repositions and shows the flyout. Cheap because the Window already exists —
-    /// we just move the AppWindow and call Show().
-    /// </summary>
     public void ShowAt()
     {
         if (_appWindow is null) return;
 
         UpdateUi();
 
-        // Recalculate target monitor every time, since the cursor may have moved.
         const int logicalWidth  = 280;
         const int logicalHeight = 165;
         int width  = (int)Math.Round(logicalWidth  * _scale);
@@ -87,23 +90,61 @@ public void ShowAt()
 
         _appWindow.MoveAndResize(new RectInt32(x, y, width, height));
         _appWindow.Show(activateWindow: true);
-        _isVisible = true;
+
+        // Drag ourselves to the foreground — necessary because the click came
+        // from the tray (Explorer.exe), so we don't automatically get focus.
+        Win32Helper.SetForegroundWindow(_hwnd);
         Activate();
+
+        _shownAt = DateTime.UtcNow;
+        _isVisible = true;
+
+        InstallForegroundHook();
     }
 
     public void HideQuiet()
     {
         if (!_isVisible || _appWindow is null) return;
         _isVisible = false;
+        UninstallForegroundHook();
         _appWindow.Hide();
     }
 
-    private void OnActivated(object sender, Microsoft.UI.Xaml.WindowActivatedEventArgs args)
+    private void InstallForegroundHook()
     {
-        if (args.WindowActivationState == WindowActivationState.Deactivated)
+        if (_hook != IntPtr.Zero) return;
+        _hookProc = OnForegroundChanged;
+        _hook = Win32Helper.SetWinEventHook(
+            Win32Helper.EVENT_SYSTEM_FOREGROUND,
+            Win32Helper.EVENT_SYSTEM_FOREGROUND,
+            IntPtr.Zero,
+            _hookProc,
+            idProcess: 0,
+            idThread: 0,
+            dwFlags: Win32Helper.WINEVENT_OUTOFCONTEXT);
+    }
+
+    private void UninstallForegroundHook()
+    {
+        if (_hook == IntPtr.Zero) return;
+        Win32Helper.UnhookWinEvent(_hook);
+        _hook = IntPtr.Zero;
+        _hookProc = null;
+    }
+
+    private void OnForegroundChanged(IntPtr hWinEventHook, uint eventType,
+        IntPtr hwnd, int idObject, int idChild, uint dwEventThread, uint dwmsEventTime)
+    {
+        // Hook fires on a non-UI thread — bounce back to the dispatcher.
+        App.Current.UIQueue.TryEnqueue(() =>
         {
-            HideQuiet();
-        }
+            if (!_isVisible) return;
+            // Ignore foreground changes during the grace period after show, so
+            // we don't dismiss before SetForegroundWindow has taken effect.
+            if (DateTime.UtcNow - _shownAt < GracePeriod) return;
+            // Hide whenever any window other than ourselves becomes foreground.
+            if (hwnd != _hwnd) HideQuiet();
+        });
     }
 
     private void OnStateChanged(object? sender, PropertyChangedEventArgs e)