feat(input): let global shortcut handlers decline so the key reaches the focused window

RegisterGlobalShortcut handlers could only consume the key — TryHandleGlobalShortcut
always returned true, and it runs before the active window is routed to, so a shortcut
could never let a key fall through to the focused window.

Add an opt-in Func<bool> overload: return true to consume, false to decline and let the
key continue down the normal pipeline (window cycle, exit key, active window). The backing
store is now Func<bool>; the existing Action overload wraps to always-consume, preserving
current behavior exactly. InputCoordinator already honors the return value, so no change
there.

- Tests: declining handler routes the key to the focused control; consuming handler
  suppresses it; the legacy Action overload still consumes.

Author: nickprotop

SharpConsoleUI.Tests/InputHandling/ShortcutsTests.cs

@@ -390,6 +390,91 @@ public void End_ScrollsToBottom()
         Assert.True(window.ScrollOffset > 30);
     }
 
+    [Fact]
+    public void GlobalShortcut_FuncReturningFalse_DeclinesAndKeyReachesFocusedControl()
+    {
+        var system = TestWindowSystemBuilder.CreateTestSystem();
+        var window = new Window(system);
+        var button = new ButtonControl { Text = "Submit" };
+        window.AddControl(button);
+        system.WindowStateService.AddWindow(window);
+        system.WindowStateService.SetActiveWindow(window);
+        window.FocusManager.SetFocus(button, FocusReason.Programmatic);
+
+        bool clicked = false;
+        button.Click += (s, e) => clicked = true;
+
+        // Declining shortcut on Enter: handler runs but returns false → key keeps routing.
+        bool handlerRan = false;
+        system.RegisterGlobalShortcut(ConsoleModifiers.None, ConsoleKey.Enter, () =>
+        {
+            handlerRan = true;
+            return false; // decline
+        });
+
+        var enterKey = new ConsoleKeyInfo('\r', ConsoleKey.Enter, false, false, false);
+        system.InputStateService.EnqueueKey(enterKey);
+        system.Input.ProcessInput();
+
+        Assert.True(handlerRan, "Declining handler should have run");
+        Assert.True(clicked, "Declined key should still reach the focused control");
+    }
+
+    [Fact]
+    public void GlobalShortcut_FuncReturningTrue_ConsumesAndKeyDoesNotReachFocusedControl()
+    {
+        var system = TestWindowSystemBuilder.CreateTestSystem();
+        var window = new Window(system);
+        var button = new ButtonControl { Text = "Submit" };
+        window.AddControl(button);
+        system.WindowStateService.AddWindow(window);
+        system.WindowStateService.SetActiveWindow(window);
+        window.FocusManager.SetFocus(button, FocusReason.Programmatic);
+
+        bool clicked = false;
+        button.Click += (s, e) => clicked = true;
+
+        bool handlerRan = false;
+        system.RegisterGlobalShortcut(ConsoleModifiers.None, ConsoleKey.Enter, () =>
+        {
+            handlerRan = true;
+            return true; // consume
+        });
+
+        var enterKey = new ConsoleKeyInfo('\r', ConsoleKey.Enter, false, false, false);
+        system.InputStateService.EnqueueKey(enterKey);
+        system.Input.ProcessInput();
+
+        Assert.True(handlerRan, "Consuming handler should have run");
+        Assert.False(clicked, "Consumed key must not reach the focused control");
+    }
+
+    [Fact]
+    public void GlobalShortcut_ActionOverload_StillConsumes()
+    {
+        var system = TestWindowSystemBuilder.CreateTestSystem();
+        var window = new Window(system);
+        var button = new ButtonControl { Text = "Submit" };
+        window.AddControl(button);
+        system.WindowStateService.AddWindow(window);
+        system.WindowStateService.SetActiveWindow(window);
+        window.FocusManager.SetFocus(button, FocusReason.Programmatic);
+
+        bool clicked = false;
+        button.Click += (s, e) => clicked = true;
+
+        // Back-compat: the Action overload always consumes (unchanged behavior).
+        bool handlerRan = false;
+        system.RegisterGlobalShortcut(ConsoleModifiers.None, ConsoleKey.Enter, () => { handlerRan = true; });
+
+        var enterKey = new ConsoleKeyInfo('\r', ConsoleKey.Enter, false, false, false);
+        system.InputStateService.EnqueueKey(enterKey);
+        system.Input.ProcessInput();
+
+        Assert.True(handlerRan, "Action handler should have run");
+        Assert.False(clicked, "Action shortcut must consume the key (key does not reach the control)");
+    }
+
     // TODO: MultilineEditControl doesn't have SelectAll() method yet
     //[Fact]
     //public void CtrlC_OnTextBox_CopiesSelection()

SharpConsoleUI/ConsoleWindowSystem.cs

@@ -103,7 +103,7 @@ public class ConsoleWindowSystem
 		private Diagnostics.RenderingDiagnostics? _renderingDiagnostics;
 
 		// Global keyboard shortcuts registered by the application
-		private readonly Dictionary<(ConsoleModifiers Modifiers, ConsoleKey Key), Action> _globalShortcuts = new();
+		private readonly Dictionary<(ConsoleModifiers Modifiers, ConsoleKey Key), Func<bool>> _globalShortcuts = new();
 
 		// Main loop watchdog — detects stalled frames and provides emergency Ctrl+Q exit
 		private readonly MainLoopWatchdog _watchdog;
@@ -1409,27 +1409,37 @@ public void RegisterSettingsPage(string name, string? icon = null,
 
 		/// <summary>
 		/// Registers a global keyboard shortcut that is handled before routing to windows.
+		/// The key is always consumed (it does not continue to the focused window). To let the
+		/// handler decide whether the key is consumed, use the <see cref="Func{TResult}"/> overload.
 		/// </summary>
 		/// <param name="modifiers">The modifier keys (e.g. Control, Alt, Shift).</param>
 		/// <param name="key">The key to bind.</param>
 		/// <param name="action">The action to invoke when the shortcut is pressed.</param>
 		public void RegisterGlobalShortcut(ConsoleModifiers modifiers, ConsoleKey key, Action action)
-		{
-			_globalShortcuts[(modifiers, key)] = action;
-		}
+			=> _globalShortcuts[(modifiers, key)] = () => { action(); return true; };
+
+		/// <summary>
+		/// Registers a global keyboard shortcut whose handler decides whether the key is consumed.
+		/// Return <c>true</c> to consume the key (stop routing); return <c>false</c> to decline,
+		/// letting the key continue down the normal pipeline (window cycle, exit key, active window).
+		/// This enables conditional shortcuts — e.g. a global Ctrl+Q that reaches a focused control
+		/// but acts globally when nothing relevant is focused.
+		/// </summary>
+		/// <param name="modifiers">The modifier keys (e.g. Control, Alt, Shift).</param>
+		/// <param name="key">The key to bind.</param>
+		/// <param name="action">
+		/// The handler to invoke; returns <c>true</c> to consume the key, <c>false</c> to decline.
+		/// </param>
+		public void RegisterGlobalShortcut(ConsoleModifiers modifiers, ConsoleKey key, Func<bool> action)
+			=> _globalShortcuts[(modifiers, key)] = action;
 
 		/// <summary>
 		/// Tries to execute a registered global shortcut for the given key info.
+		/// Returns the handler's result (<c>true</c> = consumed), or <c>false</c> when no shortcut
+		/// is registered for the key or the handler declined.
 		/// </summary>
 		internal bool TryHandleGlobalShortcut(ConsoleKeyInfo keyInfo)
-		{
-			if (_globalShortcuts.TryGetValue((keyInfo.Modifiers, keyInfo.Key), out var action))
-			{
-				action();
-				return true;
-			}
-			return false;
-		}
+			=> _globalShortcuts.TryGetValue((keyInfo.Modifiers, keyInfo.Key), out var action) && action();
 
 		#endregion