Link to issue number:

Part of #17010. Split out from #19916 at reviewer request — this is the second of three PRs. The pyphen abstraction layer was shipped in #20145; the syllable-aware wrap mode follows in a separate PR.

Summary of the issue:

The braille word-wrap setting is a single boolean that gives users no control over how words are broken at the display edge. When a word is cut mid-way there is also no visual indication that the word continues on the next row.

Description of user facing changes:

The boolean "word wrap" checkbox in the braille settings has been replaced with a Text wrap combo box with three choices:

• Off — Wrap at the raw edge of the display, cutting words in the middle if necessary. No visual indication that a word was cut.
• Show mark when words are cut — Wrap at the raw edge, but whenever a word is cut mid-way, replace the last cell of the row with a continuation mark (braille dots 7-8) so the reader knows the word continues on the next row.
• At word boundaries — Prefer breaking at spaces. If no space fits on the row, fall back to cutting the word and showing the continuation mark.

Existing config profiles with the old setting are automatically upgraded.

Description of developer facing changes:

• BrailleTextWrapFlag feature flag enum added to config.featureFlagEnums with members DEFAULT, NONE, MARK_WORD_CUTS, AT_WORD_BOUNDARIES.
• Config schema bumped v22 → v23; old wordWrap boolean is deprecated and bridged bidirectionally to textWrap via _linkDeprecatedValues, so add-ons reading or writing the old key keep working (with a deprecation warning).
• CONTINUATION_SHAPE = 0xC0 (dots 7-8) constant added to braille.
• _WindowRowPositions frozen dataclass added to braille to hold the start/end buffer positions and continuation-mark flag for each row of the braille window, replacing the previous anonymous tuple.

Description of development approach:

The continuation mark is unified: it consistently means "a word was cut here" regardless of mode, so readers get a predictable signal.

BrailleBuffer._calculateWindowRowBufferOffsets is extended to implement all three modes. Each entry in _windowRowBufferOffsets is a _WindowRowPositions instance whose showContinuationMark field records whether that row needs a continuation mark. BrailleBuffer._get_windowBrailleCells reads that flag to insert the mark. BrailleBuffer._set_windowEndPos short-circuits space-seeking for NONE and MARK_WORD_CUTS modes (backwards scroll alignment).

Testing strategy:

Unit tests cover:

• All three wrap modes and their edge cases in _calculateWindowRowBufferOffsets (no cells, fits exactly, word cut, word too long for display, no space on line).
• Continuation-mark rendering in _get_windowBrailleCells.
• Profile upgrade from wordWrap = True/False → correct textWrap flag values.

Manual testing: loaded a pre-upgrade profile with wordWrap = True/False and confirmed the upgrade writes the expected textWrap value and the braille settings panel shows the matching label.

Known issues with pull request:

None.

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.