Improve Windows Terminal caret tracking with delayed UIA updates

source/NVDAObjects/UIA/winConsoleUIA.py

@@ -455,6 +455,9 @@ class _DiffBasedWinTerminalUIA(EnhancedTermTypedCharSupport):
 	new text.
 	"""
 
+	#: Caret updates can take a while, particularly over remote connections such as SSH. (#19503)
+	_caretMovementTimeoutMultiplier = 3.0
+
 	def event_UIA_notification(self, **kwargs):
 		"Block notification events when diffing to prevent double reporting."
 		log.debugWarning(f"Notification event blocked to avoid double-report: {kwargs}")
@@ -466,6 +469,9 @@ class _NotificationsBasedWinTerminalUIA(UIA):
 	events provided by the application to speak new text.
 	"""
 
+	#: Caret updates can take a while, particularly over remote connections such as SSH. (#19503)
+	_caretMovementTimeoutMultiplier = 3.0
+
 	#: Override the role, which is controlTypes.Role.STATICTEXT by default.
 	role = controlTypes.Role.TERMINAL
 	#: New line text is announced using UIA notification events

user_docs/en/changes.md

@@ -31,6 +31,7 @@
 * The actions button can now be used when selecting multiple add-ons in the Add-on Store to perform batch actions, instead of just via the context menu in the add-ons list. (#19971, @amirmahdifard)
 * When moving to an ARIA grid cell in focus mode in web browsers, NVDA no longer reports both the row and column headers even if only the row or only the column changed. (#17750, @jcsteh)
 * In live text regions, such as terminals, NVDA no longer freezes when substantial amounts of text are dumped to the screen. (#20177, #20216, @ethindp, @codeofdusk)
+* In Windows Terminal, NVDA is less likely to report stale characters when moving the caret in delayed remote sessions such as SSH. (#19503, @sheldon-im)
 * When an application stops responding, NVDA no longer freezes or floods its log with errors; it stays responsive and drops UIA and MSAA events from the unresponsive application until it recovers. (#16749, @heath-toby)
 * Reduced lag on UI Automation text change events, improving the responsiveness of controls such as combo boxes and of File Explorer, by using the cached element class name instead of a live cross-process fetch. (#16749, @heath-toby)
 * In Notepad++, NVDA now continues to report IME composition text in speech and braille while selecting or navigating within Chinese IME composition. (#14140, #14152, @keyang556)

user_docs/en/userGuide.md

@@ -1936,6 +1936,11 @@ As new text is written, the content scroll upwards and previous text is no longe
 On Windows versions before Windows 11 22H2, text in the console that is not visibly displayed in the window is not accessible with NVDA's text review commands.
 Therefore, it is necessary to scroll the console window to read earlier text.
 In newer versions of the console and in Windows Terminal, it is possible to review the entire text buffer freely without the need to scroll the window.
+
+Windows Terminal may delay UIA caret updates, especially in remote sessions over SSH.
+NVDA waits slightly longer for caret movement in Windows Terminal, so it is less likely to report stale characters.
+If caret reporting is still inaccurate, try increasing [Caret move timeout](#AdvancedSettingsCaretMoveTimeout) in Advanced settings.
+Increasing this value may make caret movement feel slower, so consider changing it in a configuration profile for terminal applications.
 <!-- KC:beginInclude -->
 The following built-in Windows Console keyboard shortcuts may be useful when [reviewing text](#ReviewingText) with NVDA in older versions of Windows Console: