Fix runtime replacement of quit command

Author: xoofx

site/docs/commands.md

@@ -8,6 +8,8 @@ XenoAtom.Terminal.UI provides a lightweight **command system** to make keyboard
 
 Commands are **retained-mode**, registered on visuals (local) or on the `TerminalApp` (global), and routed using the same focus → parent traversal as other keyboard handling.
 
+`TerminalApp` registers a default global quit command (`TerminalApp.DefaultQuitCommandId`, value `TerminalApp.Quit`). Replacing or removing that command after the app starts also updates the live app-exit shortcut, not just command discovery surfaces.
+
 ## What is a command?
 
 A `Command` is an action with:

src/XenoAtom.Terminal.UI.Tests/CommandBarRenderingTests.cs

@@ -82,6 +82,34 @@ public void CommandBar_MultiLine_Wraps_Commands_To_Additional_Rows()
         Assert.IsTrue(alphaRow != betaRow || betaRow != gammaRow, "Expected wrapped commands to span multiple rows.");
     }
 
+    [TestMethod]
+    public void CommandBar_Refreshes_When_Global_Command_Is_Replaced_After_Run_Starts()
+    {
+        var probe = new CommandProbe();
+        var bar = new CommandBar();
+        var layout = new DockLayout { Content = probe, Bottom = bar };
+
+        using var driver = new TerminalAppTestDriver(layout, TerminalHostKind.Fullscreen, new TerminalSize(60, 6));
+        driver.App.Focus(probe);
+        driver.Tick();
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = TerminalApp.DefaultQuitCommandId,
+            LabelMarkup = "Leave",
+            Gesture = new XenoAtom.Terminal.UI.Input.KeyGesture(TerminalKey.F4),
+            Execute = _ => { },
+        });
+
+        driver.Tick();
+
+        var rendered = string.Join('\n', GetScreenLines(driver, 60, 6));
+        StringAssert.Contains(rendered, "F4");
+        StringAssert.Contains(rendered, "Leave");
+        Assert.IsFalse(rendered.Contains("Ctrl+Q", StringComparison.Ordinal), "The command bar should stop showing the original quit gesture after replacement.");
+        Assert.IsFalse(rendered.Contains("Quit", StringComparison.Ordinal), "The command bar should stop showing the original quit label after replacement.");
+    }
+
     private static string[] GetScreenLines(TerminalAppTestDriver driver, int width, int height)
     {
         var screen = new AnsiTestScreen(width, height);

src/XenoAtom.Terminal.UI.Tests/UiCommandShortcutTests.cs

@@ -2,6 +2,7 @@
 // Licensed under the BSD-Clause 2 license.
 // See license.txt file in the project root for full license information.
 
+using System.Reflection;
 using XenoAtom.Terminal.UI.Commands;
 using XenoAtom.Terminal.UI.Geometry;
 using XenoAtom.Terminal.UI.Hosting;
@@ -134,6 +135,79 @@ public void Disabled_Command_Can_Allow_Gesture_Fallthrough()
         Assert.AreEqual(1, probe.FallbackCount);
     }
 
+    [TestMethod]
+    public void Replacing_Default_Quit_Command_Updates_Runtime_Gesture_Handling()
+    {
+        var root = new EmptyProbe();
+        var invoked = false;
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(40, 10));
+        driver.Tick();
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = TerminalApp.DefaultQuitCommandId,
+            LabelMarkup = "Leave",
+            Gesture = new XenoAtom.Terminal.UI.Input.KeyGesture(TerminalKey.F4),
+            Execute = _ => invoked = true,
+        });
+
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Unknown, Char = TerminalChar.CtrlQ, Modifiers = TerminalModifiers.Ctrl });
+        driver.Tick();
+
+        Assert.IsFalse(IsStopRequested(driver.App), "Replacing TerminalApp.Quit should disable the original built-in exit gesture.");
+        Assert.IsFalse(invoked, "The replacement exit command should not run for the old gesture.");
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.F4 });
+        driver.Tick();
+
+        Assert.IsTrue(invoked, "The replacement exit command should run for its new gesture.");
+    }
+
+    [TestMethod]
+    public void Removing_Then_Readding_Default_Quit_Command_Updates_Runtime_Gesture_Handling()
+    {
+        var root = new EmptyProbe();
+        var invoked = false;
+
+        using var driver = new TerminalAppTestDriver(root, TerminalHostKind.Fullscreen, new TerminalSize(40, 10));
+        driver.Tick();
+
+        Assert.IsTrue(driver.App.RemoveGlobalCommand(TerminalApp.DefaultQuitCommandId), "Expected the default quit command to be registered.");
+
+        driver.App.AddGlobalCommand(new Command
+        {
+            Id = TerminalApp.DefaultQuitCommandId,
+            LabelMarkup = "Leave",
+            Gesture = new XenoAtom.Terminal.UI.Input.KeyGesture(TerminalKey.F4),
+            Execute = _ => invoked = true,
+        });
+
+        driver.Tick();
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.Unknown, Char = TerminalChar.CtrlQ, Modifiers = TerminalModifiers.Ctrl });
+        driver.Tick();
+
+        Assert.IsFalse(IsStopRequested(driver.App), "Removing and re-adding TerminalApp.Quit should disable the original built-in exit gesture.");
+        Assert.IsFalse(invoked, "The re-registered quit command should not run for the old gesture.");
+
+        driver.Backend.PushEvent(new TerminalKeyEvent { Key = TerminalKey.F4 });
+        driver.Tick();
+
+        Assert.IsTrue(invoked, "The re-registered quit command should run for its new gesture.");
+    }
+
+    private static bool IsStopRequested(TerminalApp app)
+    {
+        var ctsField = typeof(TerminalApp).GetField("_cts", BindingFlags.Instance | BindingFlags.NonPublic);
+        Assert.IsNotNull(ctsField, "Expected TerminalApp to expose its cancellation token source field for tests.");
+        var cts = (CancellationTokenSource?)ctsField.GetValue(app);
+        Assert.IsNotNull(cts, "Expected TerminalApp to initialize its cancellation token source.");
+        return cts.IsCancellationRequested;
+    }
+
     private sealed class EmptyProbe : Visual
     {
         protected override SizeHints MeasureCore(in LayoutConstraints constraints) => SizeHints.Fixed(constraints.Clamp(new Size(1, 1)));

src/XenoAtom.Terminal.UI/TerminalApp.cs

@@ -60,7 +60,6 @@ public sealed partial class TerminalApp : DispatcherObject, IAsyncDisposable, IV
     private Func<TerminalRunningContext, ValueTask<TerminalLoopResult>>? _onUpdate;
     private TerminalRunningContext? _updateContext;
     private readonly AnsiBuilder _updateOutputBuilder = new(initialCapacity: 4096);
-    private global::XenoAtom.Terminal.UI.Input.KeyGesture _exitGesture;
     private bool _inlineRemoveOnEnd;
     private Dictionary<string, AnsiStyle>? _previousMarkupStyles;
 
@@ -133,6 +132,15 @@ private enum SceneRenderMode
     /// </summary>
     public Func<Rune, bool> WideRuneResolver => _wideRuneResolver;
 
+    /// <summary>
+    /// Gets the command id used by the built-in application quit command.
+    /// </summary>
+    /// <remarks>
+    /// Applications can use this id to replace or re-register the default quit command through
+    /// <see cref="GlobalCommands"/>, <see cref="AddGlobalCommand(Command)"/>, and <see cref="RemoveGlobalCommand(string)"/>.
+    /// </remarks>
+    public static string DefaultQuitCommandId { get; } = "TerminalApp.Quit";
+
     /// <summary>
     /// Gets the global commands registered on this application.
     /// </summary>
@@ -284,14 +292,14 @@ internal TerminalApp(Visual root, TerminalInstance? terminal, TerminalAppOptions
             _inlineHost = new InlineInteractiveHost(_terminal);
         }
 
-        _exitGesture = _options.ExitGesture ?? GetDefaultExitGesture(_options.HostKind);
+        var exitGesture = _options.ExitGesture ?? GetDefaultExitGesture(_options.HostKind);
 
         AddGlobalCommand(new Command
         {
-            Id = "TerminalApp.Quit",
+            Id = DefaultQuitCommandId,
             LabelMarkup = "Quit",
             DescriptionMarkup = "Quit the application.",
-            Gesture = _exitGesture,
+            Gesture = exitGesture,
             Importance = CommandImportance.Primary,
             Presentation = CommandPresentation.CommandBar,
             Execute = static v => v.App?.Stop(),
@@ -2570,13 +2578,8 @@ private void HandleTerminalEvent(TerminalEvent ev)
 
         var activeModal = FindActiveModalRoot(Root);
 
-        if (_exitGesture.Matches(keyEvent))
+        if (TryHandleAppExitGesture(keyEvent))
         {
-            // Allow controls to handle the exit gesture (e.g. close transient popups) before exiting the app.
-            if (!DispatchKeyEvent(keyEvent, routeCommands: false))
-            {
-                _cts.Cancel();
-            }
             return;
         }
 
@@ -2615,6 +2618,56 @@ private void HandleTerminalEvent(TerminalEvent ev)
             ? new global::XenoAtom.Terminal.UI.Input.KeyGesture(TerminalChar.CtrlQ, TerminalModifiers.Ctrl)
             : new global::XenoAtom.Terminal.UI.Input.KeyGesture(TerminalKey.Escape);
 
+    private bool TryHandleAppExitGesture(TerminalKeyEvent keyEvent)
+    {
+        if (!TryGetDefaultQuitCommand(out var command))
+        {
+            return false;
+        }
+
+        if (command.Gesture is not { } gesture || !gesture.Matches(keyEvent))
+        {
+            return false;
+        }
+
+        // Allow controls to observe the raw gesture first (e.g. close a transient popup) before the app-level
+        // quit command runs. The command itself stays replaceable at runtime via GlobalCommands.
+        if (DispatchKeyEvent(keyEvent, routeCommands: false))
+        {
+            return true;
+        }
+
+        EnsureFocusInScope();
+        var target = FocusedElement ?? Root;
+        if (!command.IsVisibleFor(target) || !command.CanExecuteFor(target))
+        {
+            return command.ConsumesGestureWhenUnavailable;
+        }
+
+        command.Execute(target);
+        return true;
+    }
+
+    private bool TryGetDefaultQuitCommand(out Command command)
+    {
+        var commands = _globalCommands;
+        if (commands is not null)
+        {
+            for (var i = 0; i < commands.Count; i++)
+            {
+                var candidate = commands[i];
+                if (string.Equals(candidate.Id, DefaultQuitCommandId, StringComparison.Ordinal))
+                {
+                    command = candidate;
+                    return true;
+                }
+            }
+        }
+
+        command = null!;
+        return false;
+    }
+
     private void DispatchTextInput(string text)
     {
         EnsureFocusInScope();