fix(mac): improved adherence to backspace rules for compliant apps by sgschantz · Pull Request #15561 · keymanapp/keyman

sgschantz · 2026-02-04T19:59:11Z

Introduces an alternative to approach to backspace for compliant apps by using the insertText API to
replace a character to be deleted and the preceding character from the context with only the character from the context

Fixes: #15543

Build-bot: release:mac

User Testing

Preparation: install the keyboard bksp_ldml.zip
All tests should be using compliant apps such as Apple's Pages, TextEdit or Stickies.

TEST_BKSP_D_ACUTE_VERIFY_CONTEXT: In a compliant app, with the BKSP keyboard selected, type:
abc d/
Select the text, copy and paste it into a character viewer and verify that the last two characters are U+0064 U+0301.
TEST_BKSP_D_ACUTE: In a compliant app, with the BKSP keyboard selected, type:
abc d/
Then press bksp. The result should be abc d.
TEST_EUROLATIN_E_ACUTE: In a compliant app, with the EuroLatin keyboard selected, type:
caf'e
The result should be café.
Then press bksp. The result should be caf.
TEST_EUROLATIN_BACKSPACE: In a compliant app, with the EuroLatin keyboard selected, type:
abcreturnab
Then press bksp four times. The result should be ab.
TEST_REPLACE_SURROGATE_PAIR_CHARACTER: processing a character that causes the replacement of a surrogate pair produces the correct, uncorrupted output

Open the Stickies app and create a new Note
Switch to the Malar Tirhuta keyboard
Type k
Confirm that the letter 𑒏𑓂 was typed
Type e
Confirm that output now reads: 𑒏𑒹
Confirm that the text can be selected and successfully copied into a TextEdit document
Confirm that backspace deletes the letters in the order they were entered

introduces an alternative to approach to backspace for compliant apps by using the insertText API to replace a character to be deleted and the preceding character from the context with only the character from the context Fixes: #15543

keymanapp-test-bot · 2026-02-04T19:59:32Z

User Test Results

Test specification and instructions

✅ TEST_BKSP_D_ACUTE_VERIFY_CONTEXT (PASSED) (notes)
✅ TEST_BKSP_D_ACUTE (PASSED) (notes)
✅ TEST_EUROLATIN_E_ACUTE (PASSED) (notes)
✅ TEST_EUROLATIN_BACKSPACE (PASSED) (notes)
✅ TEST_REPLACE_SURROGATE_PAIR_CHARACTER (PASSED) (notes)

Test Artifacts

macOS
- Keyman for macOS
- Keyman for macOS (old PRs)

Meng-Heng · 2026-02-06T06:59:35Z

Test Specs

macOS Sequoia
TextEdit v1.20
Keyman 19.0.198-alpha-test-15561

Test Results

TEST_BKSP_D_ACUTE_VERIFY_CONTEXT (PASSED):

In TextEdit, type abc d/
Select, Copy, and Paste into unicode.scarfboy.com
Verify: The last two characters are U+0064 U+0301.

TEST_BKSP_D_ACUTE (PASSED):

In TextEdit, type abc d/
Press bksp
Verify: the result is abc d.

TEST_EUROLATIN_E_ACUTE (PASSED):

In TextEdit with EuroLatin (SIL) keyboard
Type caf'e, result is café
Press bksp
Verify: The result is caf.

TEST_EUROLATIN_BACKSPACE (PASSED):

In TextEdit with EuroLatin (SIL) keyboard
Type abcreturnab
Press bksp 4 times
Verify: The result is ab.

mcdurdin

This looks really good -- it's a clear and easy to follow function. I think we need to cover off the surrogate pair scenario for completeness.

I have tried to write a background description in the function header comment because the 'why' for this I think will be unclear to future maintainers. Feel free to adapt especially if I have gotten any details wrong.

mac/Keyman4MacIM/Keyman4MacIM/KMInputMethodEventHandler.m

mcdurdin · 2026-02-07T20:50:49Z

mac/Keyman4MacIM/Keyman4MacIM/KMInputMethodEventHandler.m

+  if ((self.apiCompliance.canReplaceText) && ([context length] > codePointsToDelete)) {
+    int codePointsToReplace = codePointsToDelete + 1;
+    NSRange replacementStringRange = NSMakeRange([context length] - codePointsToReplace, 1);
+    NSString *replacementString = [context substringWithRange:replacementStringRange];
+
+    // replace only works for non-control characters
+    // if replacementString contains control characters, then return without handling event
+    NSString *message = nil;
+    if ([self containsControlCharacter:replacementString]) {
+      message = @"handleDeleteByReplace, replacementString contains control characters, cannot delete with replace";
+      os_log_debug([KMLogs keyTraceLog], "%@", message);
+      [KMSentryHelper addDebugBreadCrumb:@"event" message:message];
+      return NO;
+    } else {
+      message = @"handleDeleteByReplace, canReplaceText == true";
+      os_log_debug([KMLogs keyTraceLog], "%@", message);
+      [KMSentryHelper addDebugBreadCrumb:@"event" message:message];
+      handledEvent = YES;
+    }
+
+    NSRange replacementRange = NSMakeRange(replacementStringRange.location, codePointsToReplace);
+    [client insertText:replacementString replacementRange:replacementRange];
+  }


Sorry to make your life more difficult here, but I think we need to make sure this works even with non-BMP characters (U+10000 - U+10FFFF) because it's not clear to me that splitting a surrogate pair in the replacement will work consistently -- even though it's effectively not changing, some apps may reject the transform due to encoding boundaries or safety concerns.

That was a worthwhile test! I tried with the Malar Tirhuta keyboard, and after typing 𑒏𑒹 (U+1148F U+114B9) and hitting backspace, it only deleted the second half of the surrogate pair, leaving me with U+1148F U+FFFD

I could check the character that core tells me to delete and behave differently if it is a surrogate pair: either resort to the passthrough/generate backspace or, probably riskier, look for a match between the delete string returned from core and the context and try to replace more of the string.

I tried finding APIs that know more about the Unicode string without checking for specific character ranges, but what I found didn't work. There may be better support with the Swift Unicode APIs, so we may have better options when we move the Input Method to Swift in Keyman 20+.

It looks like the key is to examine the character that precedes the substring that core instructs us to delete and see whether it is part of a 'composed character'. In the macOS APIs, both surrogate pairs and characters with combining diacritics or vowels are considered to be composed characters.

If we try to delete by letting the backspace event pass through, then it seems the system will delete an entire composed character. If we delete using the character index, then we may delete a partial character and cut something in half.

So when we delete by replacing, we need to check the previous character, and, if it is a composed character, use the whole thing for the replacement. This will prevent breaking up surrogates pairs.

Keyman Core may instruct us to delete something that is part of what macOS considers to be the same composed character. In that case, we can see if the code unit that core instructs us to delete and the code unit preceding it in the context are both part of the same composed character. We can do this by calling the following API for each index in the string: rangeOfComposedCharacterSequenceAtIndex

An example of this scenario would be the test case TEST_BKSP_D_ACUTE

If this is the right approach, I am still not sure whether there is a way to distinguish the difference between deleting the diacritic for that test case and the combining vowel (which is a surrogate pair on its own) in the Malar Tirhuta case.

I think we should treat surrogate pairs differently to clusters. As far as I can tell, a compliant app needs only the surrogate pair handling for correct deletion via the insertText API, and so we should do just that there.

Non-compliant apps are a whole separate can of worms. In non-compliant apps, cluster awareness seems like it would be a really good way to approach a more robust backspacing model, but we do run the risk of being too clever for some apps which 'naively' only delete a single codepoint on backspace. This should be tracked as a new issue (is it related to #10246?)

Co-authored-by: Marc Durdin <marc@durdin.net>

deals with preceding character being a surrogate pair when a delete occurs Fixes: #15543

re-review

Meng-Heng · 2026-02-20T01:55:11Z

Test Specs

Stickies v10.3
TextEdit v1.20
macOS Sequoia 15.7.4

Test Prerequisites

Install Keyman 19.0.198-alpha-test-15561
Download Malar Tarhuta keyboard

Test Results

TEST_REPLACE_SURROGATE_PAIR_CHARACTER (PASSED):

Create a New Note in Stickies
Type k
Verify: Output is 𑒏𑓂
Type e
Verify: Output is 𑒏𑒹
Select, copy, and paste into TextEdit
Verify: Text is 𑒏𑒹
Press bksp
Verify: The text outputs 𑒏 (was deleted in the order it was entered)

fix(mac): improved adherence to backspace rule

65c151b

introduces an alternative to approach to backspace for compliant apps by using the insertText API to replace a character to be deleted and the preceding character from the context with only the character from the context Fixes: #15543

sgschantz added this to the A19S22 milestone Feb 4, 2026

sgschantz requested a review from mcdurdin February 4, 2026 19:59

sgschantz self-assigned this Feb 4, 2026

sgschantz added this to Keyman Feb 4, 2026

sgschantz added the mac/ label Feb 4, 2026

github-project-automation bot moved this to Todo in Keyman Feb 4, 2026

github-actions bot added the fix label Feb 4, 2026

sgschantz mentioned this pull request Feb 4, 2026

bug(mac): Google apps producing unexpected output with Safari and macOS 26 Tahoe #14879

Closed

8 tasks

keymanapp-test-bot bot added has-user-test user-test-required User tests have not been completed labels Feb 5, 2026

keymanapp-test-bot bot removed the user-test-required User tests have not been completed label Feb 6, 2026

mcdurdin previously requested changes Feb 7, 2026

View reviewed changes

sgschantz and others added 2 commits February 10, 2026 21:53

Update mac/Keyman4MacIM/Keyman4MacIM/KMInputMethodEventHandler.m

c2a6676

Co-authored-by: Marc Durdin <marc@durdin.net>

Apply suggestions from code review

553a2e5

Co-authored-by: Marc Durdin <marc@durdin.net>

keyman-server modified the milestones: A19S22, A19S23 Feb 13, 2026

fix(mac): improved adherence to backspace rule

f8e9f72

deals with preceding character being a surrogate pair when a delete occurs Fixes: #15543

keymanapp-test-bot bot added the user-test-required User tests have not been completed label Feb 14, 2026

mcdurdin self-requested a review February 18, 2026 15:56

keymanapp-test-bot bot removed the user-test-required User tests have not been completed label Feb 20, 2026

sgschantz mentioned this pull request Feb 23, 2026

bug(mac): backspace a Khmer consonant result in outputs of the vowel before the consonant #15592

Open

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

fix(mac): improved adherence to backspace rules for compliant apps#15561

fix(mac): improved adherence to backspace rules for compliant apps#15561
sgschantz wants to merge 4 commits intomasterfrom
fix/mac/15543-backspace

sgschantz commented Feb 4, 2026 •

edited

Loading

Uh oh!

keymanapp-test-bot bot commented Feb 4, 2026 •

edited

Loading

Uh oh!

Meng-Heng commented Feb 6, 2026

Uh oh!

mcdurdin left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcdurdin Feb 7, 2026

Uh oh!

sgschantz Feb 11, 2026

Uh oh!

sgschantz Feb 12, 2026

Uh oh!

mcdurdin Feb 16, 2026

Uh oh!

Meng-Heng commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Comments

Conversation

sgschantz commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Testing

Uh oh!

keymanapp-test-bot bot commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Test Results

Test Artifacts

Uh oh!

Meng-Heng commented Feb 6, 2026

Test Specs

Test Results

Uh oh!

mcdurdin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcdurdin Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

sgschantz Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

sgschantz Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

mcdurdin Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Meng-Heng commented Feb 20, 2026

Test Specs

Test Prerequisites

Test Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sgschantz commented Feb 4, 2026 •

edited

Loading

keymanapp-test-bot bot commented Feb 4, 2026 •

edited

Loading