Deliver letter and digit keys on macOS so Command shortcuts work, and stop the beep

TranslateKeyCode only named special keys, so every letter and digit arrived
as Keys.None and no Command (or Control) shortcut ever matched: ⌘S, ⌘Z, ⌘Y,
⌘A, ⌘C/V/X, ⌘+/⌘- and text-field copy/paste were all dead. Resolve the key
from charactersIgnoringModifiers when the key-code table has no entry.

Command chords were deliberately left unhandled so menu key equivalents could
run, but the app installs no NSMenu, so they fell through to NSBeep. Swallow
them like every other key down (still skipping OnKeyPress so ⌘S does not type
an "s"); noted in DispatchEvent for whenever a main menu is added.

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

Author: larsbrubaker

PlatformMac/mac/MacSystemWindow.cs

@@ -1478,11 +1478,15 @@ private static void PumpEvents()
 		/// Hands an event to the agg window it belongs to.
 		/// </summary>
 		/// <returns>
-		/// True when AppKit must <em>not</em> also see the event. Only unmodified key events are swallowed:
-		/// the content view is a plain NSView with no key handling, so letting a keystroke walk the
-		/// responder chain ends at NSBeep. Command-modified keys are passed on so menu equivalents and
-		/// Cmd-Q keep working, and every mouse event is passed on because title-bar dragging, live resize
-		/// and the close button are all AppKit's to handle.
+		/// True when AppKit must <em>not</em> also see the event. Every key event is swallowed: the content
+		/// view is a plain NSView with no key handling, so letting a keystroke walk the responder chain
+		/// ends at NSBeep. That includes Command chords, which used to be passed on for menu key
+		/// equivalents - the application installs no NSMenu, so there were no equivalents to reach and
+		/// every Cmd-shortcut the application itself handled beeped on top of doing its work. If a main
+		/// menu is ever installed, unhandled Command chords will need forwarding again.
+		/// <para/>
+		/// Every mouse event is passed on because title-bar dragging, live resize and the close button are
+		/// all AppKit's to handle.
 		/// </returns>
 		private static bool DispatchEvent(IntPtr nsEvent)
 		{
@@ -1760,18 +1764,17 @@ internal static ulong ReleaseAppliedModifierKeys(IReadOnlySet<Keys> appliedModif
 		private bool HandleKeyDown(IntPtr nsEvent)
 		{
 			ulong flags = Send_Q(nsEvent, Sel("modifierFlags"));
-			Keys modifiers = TranslateModifiers(flags);
-			Keys keyCode = TranslateKeyCode(Send_u(nsEvent, Sel("keyCode")));
+			var keyEvent = MakeKeyEventArgs(nsEvent, flags);
 
-			var keyEvent = new KeyEventArgs(keyCode | modifiers);
 			this.aggSystemWindow.OnKeyDown(keyEvent);
 			Keyboard.SetKeyDownState(keyEvent.KeyCode, true);
 
-			// Command-modified keys are menu equivalents; agg gets a look but AppKit must still see them.
+			// A Command chord is a shortcut, never text, so it stops at the key down - typing Cmd-S must
+			// not also insert an "s" into whatever has focus.
 			bool commandHeld = (flags & NSEventModifierFlagCommand) != 0;
 			if (commandHeld)
 			{
-				return false;
+				return true;
 			}
 
 			if (!keyEvent.SuppressKeyPress)
@@ -1801,9 +1804,7 @@ private bool HandleKeyDown(IntPtr nsEvent)
 
 		private bool HandleKeyUp(IntPtr nsEvent)
 		{
-			Keys modifiers = TranslateModifiers(Send_Q(nsEvent, Sel("modifierFlags")));
-			Keys keyCode = TranslateKeyCode(Send_u(nsEvent, Sel("keyCode")));
-			var keyEvent = new KeyEventArgs(keyCode | modifiers);
+			var keyEvent = MakeKeyEventArgs(nsEvent, Send_Q(nsEvent, Sel("modifierFlags")));
 
 			// Only process the key up if we saw the key down, matching the Windows sink.
 			if (Keyboard.IsKeyDown(keyEvent.KeyCode))
@@ -1812,7 +1813,90 @@ private bool HandleKeyUp(IntPtr nsEvent)
 				Keyboard.SetKeyDownState(keyEvent.KeyCode, false);
 			}
 
-			return (Send_Q(nsEvent, Sel("modifierFlags")) & NSEventModifierFlagCommand) == 0;
+			// Swallowed for the same reason a key down is, Command chords included.
+			return true;
+		}
+
+		/// <summary>
+		/// Reads the parts of a key NSEvent that decide which agg key it is, and composes the event args.
+		/// </summary>
+		private KeyEventArgs MakeKeyEventArgs(IntPtr nsEvent, ulong flags)
+		{
+			return MakeKeyEventArgs(
+				Send_u(nsEvent, Sel("keyCode")),
+				FromNSString(Send_r(nsEvent, Sel("charactersIgnoringModifiers"))),
+				flags);
+		}
+
+		/// <summary>
+		/// Composes the agg key event a keyDown or keyUp carries, from the three parts of the NSEvent that
+		/// determine it.
+		/// </summary>
+		/// <remarks>
+		/// Pure - no ObjC calls, no state - so the whole key translation can be exercised without a window,
+		/// in the same spirit as <see cref="ModifierDownStateKeys"/>.
+		/// </remarks>
+		internal static KeyEventArgs MakeKeyEventArgs(ushort virtualKey, string charactersIgnoringModifiers, ulong flags)
+		{
+			Keys keyCode = TranslateKeyCode(virtualKey);
+
+			if (keyCode == Keys.None)
+			{
+				keyCode = TranslateCharacterKey(charactersIgnoringModifiers);
+			}
+
+			return new KeyEventArgs(keyCode | TranslateModifiers(flags));
+		}
+
+		/// <summary>
+		/// Maps the layout-resolved text of a key onto agg's <see cref="Keys"/>, for the letters and digits
+		/// <see cref="TranslateKeyCode"/> deliberately does not name.
+		/// </summary>
+		/// <remarks>
+		/// A virtual key code is a hardware position - 0x01 is "where S sits on a US layout" and is a
+		/// different letter on an AZERTY one - so the key code table cannot answer "which letter is this".
+		/// Shortcuts are all spelled as key codes (Ctrl+S, Ctrl+Z, Ctrl+A), so without this every one of
+		/// them arrived as a bare Control modifier with <see cref="Keys.None"/> attached and matched
+		/// nothing: Cmd-S did not save, it only beeped.
+		/// <para/>
+		/// <c>-[NSEvent charactersIgnoringModifiers]</c> is the source because it resolves the layout while
+		/// factoring Command and Option back out - Option-S is "s" here and the dead-key text only in
+		/// <c>characters</c>. Shift is <em>not</em> factored out, so each shifted spelling has to be mapped
+		/// onto the same key its unshifted spelling gives, which is what WinForms reports either way.
+		/// </remarks>
+		internal static Keys TranslateCharacterKey(string charactersIgnoringModifiers)
+		{
+			if (string.IsNullOrEmpty(charactersIgnoringModifiers))
+			{
+				return Keys.None;
+			}
+
+			char character = char.ToUpperInvariant(charactersIgnoringModifiers[0]);
+
+			if (character >= 'A' && character <= 'Z')
+			{
+				return Keys.A + (character - 'A');
+			}
+
+			if (character >= '0' && character <= '9')
+			{
+				return Keys.D0 + (character - '0');
+			}
+
+			switch (character)
+			{
+				// The zoom shortcuts, with the shifted spelling of each key alongside the unshifted one.
+				case '=':
+				case '+':
+					return Keys.Oemplus;
+
+				case '-':
+				case '_':
+					return Keys.OemMinus;
+
+				default:
+					return Keys.None;
+			}
 		}
 
 		/// <summary>

Tests/Agg.Tests/Agg.UI/MacKeyTranslationTests.cs

@@ -0,0 +1,146 @@
+/*
+Copyright (c) 2026, Lars Brubaker
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those
+of the authors and should not be interpreted as representing official policies,
+either expressed or implied, of the FreeBSD Project.
+*/
+
+using System.Threading.Tasks;
+using MatterHackers.Agg.Platform.Mac;
+using TUnit.Assertions;
+using TUnit.Assertions.Extensions;
+using TUnit.Core;
+
+using static MatterHackers.Agg.Platform.Mac.AppKitConstants;
+
+namespace MatterHackers.Agg.UI.Tests
+{
+	/// <summary>
+	/// A keyDown carries a hardware key position, not a letter, so every letter and digit shortcut has to
+	/// be resolved from the layout-resolved characters instead. Without that, Cmd+S arrived as a bare
+	/// Control modifier with no key attached and no shortcut in the application could ever match it.
+	/// </summary>
+	public class MacKeyTranslationTests
+	{
+		/// <summary>The US-layout hardware position of S; on another layout it is another letter, which is
+		/// exactly why a key code cannot be what a letter shortcut is matched on.</summary>
+		private const ushort VkSOnUsLayout = 0x01;
+
+		[Test]
+		public async Task CommandSIsControlS()
+		{
+			KeyEventArgs keyEvent = MacSystemWindow.MakeKeyEventArgs(VkSOnUsLayout, "s", NSEventModifierFlagCommand);
+
+			await Assert.That(keyEvent.KeyCode).IsEqualTo(Keys.S);
+			await Assert.That(keyEvent.Control).IsTrue();
+		}
+
+		[Test]
+		public async Task PhysicalControlSIsAlsoControlS()
+		{
+			KeyEventArgs keyEvent = MacSystemWindow.MakeKeyEventArgs(VkSOnUsLayout, "s", NSEventModifierFlagControl);
+
+			await Assert.That(keyEvent.KeyCode).IsEqualTo(Keys.S);
+			await Assert.That(keyEvent.Control).IsTrue();
+		}
+
+		/// <summary>The everyday shortcuts, each of which was equally dead before the letters resolved.</summary>
+		[Test]
+		[Arguments("z", Keys.Z)]
+		[Arguments("y", Keys.Y)]
+		[Arguments("a", Keys.A)]
+		[Arguments("c", Keys.C)]
+		[Arguments("v", Keys.V)]
+		[Arguments("x", Keys.X)]
+		public async Task CommandLetterShortcutsResolve(string characters, Keys expected)
+		{
+			KeyEventArgs keyEvent = MacSystemWindow.MakeKeyEventArgs(0, characters, NSEventModifierFlagCommand);
+
+			await Assert.That(keyEvent.KeyCode).IsEqualTo(expected);
+			await Assert.That(keyEvent.Control).IsTrue();
+		}
+
+		/// <summary>
+		/// charactersIgnoringModifiers drops Command and Option but keeps Shift, so a shifted key arrives
+		/// spelled differently while WinForms reports the same key code either way.
+		/// </summary>
+		[Test]
+		public async Task ShiftedSpellingsShareTheirKeyCode()
+		{
+			KeyEventArgs shiftedZ = MacSystemWindow.MakeKeyEventArgs(
+				0,
+				"Z",
+				NSEventModifierFlagCommand | NSEventModifierFlagShift);
+
+			await Assert.That(shiftedZ.KeyCode).IsEqualTo(Keys.Z);
+			await Assert.That(shiftedZ.Control).IsTrue();
+			await Assert.That(shiftedZ.Shift).IsTrue();
+
+			// The 3D view's zoom shortcuts: Cmd+= and Cmd++ are one key, as are Cmd+- and Cmd+_.
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, "=", NSEventModifierFlagCommand).KeyCode)
+				.IsEqualTo(Keys.Oemplus);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, "+", NSEventModifierFlagCommand).KeyCode)
+				.IsEqualTo(Keys.Oemplus);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, "-", NSEventModifierFlagCommand).KeyCode)
+				.IsEqualTo(Keys.OemMinus);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, "_", NSEventModifierFlagCommand).KeyCode)
+				.IsEqualTo(Keys.OemMinus);
+		}
+
+		[Test]
+		public async Task DigitsResolve()
+		{
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, "1", 0).KeyCode).IsEqualTo(Keys.D1);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, "0", 0).KeyCode).IsEqualTo(Keys.D0);
+		}
+
+		/// <summary>
+		/// The named keys have to keep winning: their characters are private-use-area codes that are not
+		/// text and must never be mistaken for one.
+		/// </summary>
+		[Test]
+		public async Task NamedKeysBeatTheirCharacters()
+		{
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(VkForwardDelete, "", 0).KeyCode)
+				.IsEqualTo(Keys.Delete);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(VkReturn, "\r", 0).KeyCode).IsEqualTo(Keys.Enter);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(VkEscape, "", 0).KeyCode).IsEqualTo(Keys.Escape);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(VkDelete, "", 0).KeyCode).IsEqualTo(Keys.Back);
+		}
+
+		/// <summary>A dead key, or a character agg has no key for, still has to carry its modifiers.</summary>
+		[Test]
+		public async Task UnknownCharactersAreNoKeyButKeepTheirModifiers()
+		{
+			KeyEventArgs keyEvent = MacSystemWindow.MakeKeyEventArgs(0, "é", NSEventModifierFlagCommand);
+
+			await Assert.That(keyEvent.KeyCode).IsEqualTo(Keys.None);
+			await Assert.That(keyEvent.Control).IsTrue();
+
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, null, 0).KeyCode).IsEqualTo(Keys.None);
+			await Assert.That(MacSystemWindow.MakeKeyEventArgs(0, string.Empty, 0).KeyCode).IsEqualTo(Keys.None);
+		}
+	}
+}