Link to issue number:

Closes #17010

Summary of the issue:

Word wrap is sometimes pretty aggressive, especially on shorter braille displays.

Description of user facing changes:

The boolean "word wrap" option in the braille settings has been replaced with a four-valued Text wrap option, giving finer-grained control over how words are broken when they don't fit on the display. The four choices are:

• 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.
• At word or syllable boundaries — As above, but when a word is too long to fit, try to split it at a syllable boundary (using hyphenation dictionaries from the pyphen library) so less of the word spills onto the next row. NVDA marks the split with braille dots 7-8, not a printed hyphen, because braille conventions use word division rather than print-style hyphenation.

Whenever a word is cut mid-way across rows — regardless of which mode is selected — the cut is now marked with the continuation symbol. This makes it easy to tell at a glance whether a row ends cleanly at a space or carries over into the next row.

Existing user profiles with the old wordWrap = True / wordWrap = False setting are automatically upgraded: True becomes "At word boundaries" and False becomes "Off".

Description of developer facing changes:

The deprecated braille.wordWrap boolean is bridged to the new braille.textWrap feature flag in both directions via _linkDeprecatedValues, so add-ons that still read or write the old key keep working (with a deprecation warning).

Description of development approach:

• Feature flag. Added BrailleTextWrapFlag with members DEFAULT, NONE, MARK_WORD_CUTS, AT_WORD_BOUNDARIES, AT_WORD_OR_SYLLABLE_BOUNDARIES. The default behaviour is AT_WORD_OR_SYLLABLE_BOUNDARIES.
• Unified continuation marker. The continuation mark consistently means "a word was cut here" across all modes.
• Hyphenation module. New textUtils.hyphenation module wraps the pyphen library. getHyphenPositions(text, locale) returns an empty tuple for locales without a pyphen dictionary (logging once at debug level per locale), so the wrap logic falls back cleanly to word-boundary behaviour without raising.
• Region language tracking. Region._languageIndexes records language changes within a braille region so hyphenation can be performed in the correct language when regions contain multilingual content.
• Frozen builds. A py2exe hook (_hook_pyphen in source/setup.py) bundles pyphen's *.dic files into dist/pyphenDictionaries/ and rewrites pyphen's dictionary lookup path at freeze time. Only the .dic files are included — README files are skipped.
• Profile upgrade. upgradeConfigFrom_22_to_23 maps the old wordWrap boolean to the new textWrap string enum.

Testing strategy:

Automated unit tests cover:

• All four wrap modes in _calculateWindowRowBufferOffsets, including the case where no whitespace fits on the row, the syllable-boundary success path, the fallback when no syllable boundary fits before the display edge, and the unknown-language case.
• Continuation-marker rendering in _get_windowBrailleCells.
• Region language-index bookkeeping: default language lookup, _addFieldText inserting switch/restore entries when a field is in a different language, _addTextWithFields handling a formatChange command with a language attribute, and TextInfoRegion.update resetting the language index across updates.
• textUtils.hyphenation.getHyphenPositions for both a known language (en_US) and an unknown one (returns () without raising).

Manual testing: loaded a pre-upgrade profile with wordWrap = True/False and confirmed the profile upgrade writes the expected textWrap value and that the braille settings panel shows the matching label; confirmed scons.bat dist produces dist/pyphenDictionaries/ containing only hyph_*.dic files.

Known issues with pull request:.

Unit tests were written by AI and are a bit difficult to parse, though the behavior has been manually tested too and the unit tests ensure that the behavior stays stable.

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.