Fix UIA text unit crash and Word sentence-nav boundary wraparound

[LeonarddeR]

Link to issue number:

Follow-up to #19367.
based on beta because it fixes a feature introduced in said branch that has not yet been released.

Summary of the issue:

While wiring native Word sentence navigation into WordDocumentTextInfo.expand()/move() for UNIT_SENTENCE (related to #20467), two issues surfaced:

1. UIATextInfo.expand()/move() raise an uncaught KeyError for any NVDA text unit UIA has no mapping for, instead of a NotImplementedError, which is the contract TextInfo.expand()/move() callers rely on for a graceful no-op. UNIT_SENTENCE is one such unmapped unit, so calling expand()/move() with it on a UIA TextInfo crashed instead of raising cleanly.
2. Word's native MoveBySentence/ExpandToEnclosingSentence UIA extensions silently wrap around at document boundaries instead of stopping. Moving forward from the last sentence (or expanding a collapsed range at the very end of the document) teleports the range to the start of the document rather than staying put.

Description of user facing changes:

• Moving by sentence in Word (alt+downArrow/alt+upArrow) at the start/end of a document now stops there instead of wrapping around to the opposite end.
• No new user-facing feature: this is a fix to code introduced in UI Automation in Microsoft Word: Use move by sentence custom pattern when available instead of the legacy model #19367, which itself has no changes.md entry as it was an internal backend swap.

Description of developer facing changes:

• Added UIAHandler.getUIAUnitFromNVDAUnit(), which raises NotImplementedError instead of letting a KeyError escape NVDAUnitsToUIAUnits lookups. UIATextInfo.expand()/move() now use it. This is a general robustness fix for the UIA TextInfo API, strictly spoken independent of sentence navigation but definitely a show stopper for Restore sentence as the default say all reading unit, with a setting to read by paragraph or line #20467. It feels more appropriate to fix this in the current PR instead of in Restore sentence as the default say all reading unit, with a setting to read by paragraph or line #20467.
• UIAHandler.remote.msWord_moveTextRangeBySentence() is split into msWord_textRange_moveBySentence(), msWord_textRange_moveEndpointBySentence(), and msWord_textRange_expandToEnclosingSentence().
• As msWord_moveTextRangeBySentence is UIA-remote-ops-internal API that has only ever shipped in 2026.2 betas (no stable release), and this branch targets beta, the rename drops the function outright rather than keeping a deprecated back-compat shim.

Description of development approach:

• Wired native Word sentence support directly into WordDocumentTextInfo.expand()/move() for UNIT_SENTENCE. The sentence-navigation script now goes through this TextInfo API instead of calling the remote op directly.
• Added a boundary guard in UIAHandler.remote.msWord_textRange_expandToEnclosingSentence(): a collapsed range at the very end of the document is returned unchanged instead of being expanded to the first sentence in the document.

Testing strategy:

• Added unit tests for getUIAUnitFromNVDAUnit() (mapped and unmapped units).
• Manually verified in Word: moving by sentence (alt+downArrow/alt+upArrow) at the start/end of a document stops instead of wrapping.

Known issues with pull request:

• Need to decide whether UIAHandler.getUIAUnitFromNVDAUnit() belongs in this pr, in Restore sentence as the default say all reading unit, with a setting to read by paragraph or line #20467 or in a separate one against master. Note that NotImplementedError is a well-established exception raised by TextInfo.move and TextInfo.expand whereas KeyError is a strange outlier.
• Need to decide whether it is safe to rename msWord_moveTextRangeBySentence in this stage of development.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

[LeonarddeR]

@codeofdusk Could you please share your thoughts here?

[seanbudd]

If there's no user facing changes, do we need to take this PR to beta? It seems complicated and risky.

[LeonarddeR]

If there's no user facing changes,

That is not correct. This fixes an issue where sentence nav wraps at the bottom of a document. So currently in Word, if you have a document with Hello. Cheese. Test., word will do:

• Hello.
• Cheese.
• Test.
• Blank
• Hello.
• Cheese.
• Etc.

Do we need to take this PR to beta? It seems complicated and risky.

The reason why I filed this against beta initially is that it changes the msWord_moveTextRangeBySentence return type, which is an API breaking change. The current implementation of ``msWord_moveTextRangeBySentence` is not compatible with thext info move, because it also auto expands.

@seanbudd What would you suggest to limit the change to a minimum? E.g. making msWord_moveTextRangeBySentence private? Deprecating it in 2026.3 feels odd.

[SaschaCowley]

This looks alright to me. @seanbudd are you happy accepting this to beta this late? Note that it contains what would be API breaking changes if introduced in a future release.

[seanbudd]

Yes, let's merge this