patches: review fixes — comments, echo area, doc updates

patches/0008-ns-announce-child-frame-completion-candidates-for-Vo.patch

@@ -1,4 +1,4 @@
-From 1e2f86a698a9157a43356816a4a221fe3b70beee Mon Sep 17 00:00:00 2001
+From 240373a4a61b387dcbd1bf422ffcf4309db03039 Mon Sep 17 00:00:00 2001
 From: Martin Sukany <martin@sukany.cz>
 Date: Sat, 28 Feb 2026 16:01:29 +0100
 Subject: [PATCH 8/8] ns: announce child frame completion candidates for
@@ -17,14 +17,14 @@ FRAME_PARENT_FRAME; call announceChildFrameCompletion.  Post
 NSAccessibilityFocusedUIElementChangedNotification on the parent buffer
 element when a child frame completion closes.
 ---
- doc/emacs/macos.texi |   6 -
+ doc/emacs/macos.texi |  14 +-
- etc/NEWS             |   4 +-
+ etc/NEWS             |  16 +-
  src/nsterm.h         |   9 ++
- src/nsterm.m         | 353 +++++++++++++++++++++++++++++++++++++++++--
+ src/nsterm.m         | 373 ++++++++++++++++++++++++++++++++++++++++---
- 4 files changed, 349 insertions(+), 23 deletions(-)
+ 4 files changed, 381 insertions(+), 31 deletions(-)
 
 diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
-index 6514dfc..f47929e 100644
+index 6514dfc..95a8d15 100644
 --- a/doc/emacs/macos.texi
 +++ b/doc/emacs/macos.texi
 @@ -278,7 +278,6 @@ restart Emacs to access newly-available services.
@@ -35,7 +35,7 @@ index 6514dfc..f47929e 100644
  
    When built with the Cocoa interface on macOS, Emacs exposes buffer
  content, cursor position, mode lines, and interactive elements to the
-@@ -309,11 +308,6 @@ Shift-modified movement announces selected or deselected text.
+@@ -309,10 +308,15 @@ Shift-modified movement announces selected or deselected text.
    The @file{*Completions*} buffer announces each completion candidate
  as you navigate, even while keyboard focus remains in the minibuffer.
  
@@ -43,25 +43,45 @@ index 6514dfc..f47929e 100644
 -cursor automatically when set to follow keyboard focus.  The cursor
 -position is communicated via @code{UAZoomChangeFocus} and the
 -@code{AXBoundsForRange} accessibility attribute.
--
++  Echo area messages are announced automatically.  When a background
++operation completes and displays a message (e.g., @samp{Git finished},
++@samp{Wrote file}), VoiceOver reads it without requiring any action.
++Messages are suppressed while the minibuffer is active (i.e., while
++you are typing a command) to avoid interrupting prompt reading.
++
++  VoiceOver's rotor browse cursor stays synchronized with the Emacs
++cursor after large programmatic jumps (for example, heading navigation
++in Org mode, @code{xref-find-definitions}, or @code{imenu}).
+ 
  @vindex ns-accessibility-enabled
    To disable the accessibility interface entirely (for instance, to
- eliminate overhead on systems where assistive technology is not in
 diff --git a/etc/NEWS b/etc/NEWS
-index 2b1f9e6..8a40850 100644
+index 2b1f9e6..d276aa6 100644
 --- a/etc/NEWS
 +++ b/etc/NEWS
-@@ -4404,8 +4404,8 @@ send user data to Apple's speech recognition servers.
+@@ -4404,12 +4404,16 @@ send user data to Apple's speech recognition servers.
  ** VoiceOver accessibility support on macOS.
  Emacs now exposes buffer content, cursor position, and interactive
  elements to the macOS accessibility subsystem (VoiceOver).  This
 -includes AXBoundsForRange for macOS Zoom cursor tracking, line and
 -word navigation announcements, Tab-navigable interactive spans
-+includes line and word navigation announcements, Tab-navigable
+-(buttons, links, completion candidates), and completion announcements
-+interactive spans
+-for the *Completions* buffer.  The implementation uses a virtual
- (buttons, links, completion candidates), and completion announcements
+-accessibility tree with per-window elements, hybrid SelectedTextChanged
- for the *Completions* buffer.  The implementation uses a virtual
+-and AnnouncementRequested notifications, and thread-safe text caching.
- accessibility tree with per-window elements, hybrid SelectedTextChanged
++includes:
++- Line and word navigation announcements via standard movement keys.
++- Echo area messages (e.g., "Wrote file", "Git finished") announced
++  automatically as they appear, without user interaction.
++- VoiceOver rotor cursor synchronization after large programmatic
++  jumps (]], M-<, xref, imenu, etc.).
++- Tab-navigable interactive spans (buttons, links, completion
++  candidates) within a buffer.
++- Completion announcements for the *Completions* buffer and overlay
++  and child-frame completion UIs (Vertico, Corfu, Company-box).
+ Set 'ns-accessibility-enabled' to nil to disable the accessibility
+ interface and eliminate the associated overhead.
+ 
 diff --git a/src/nsterm.h b/src/nsterm.h
 index 21a93bc..bbce9fe 100644
 --- a/src/nsterm.h
@@ -97,7 +117,7 @@ index 21a93bc..bbce9fe 100644
  @end
  
 diff --git a/src/nsterm.m b/src/nsterm.m
-index 8d44b5f..2f4e25f 100644
+index 8d44b5f..e39a012 100644
 --- a/src/nsterm.m
 +++ b/src/nsterm.m
 @@ -7415,6 +7415,112 @@ visual line index for Zoom (skip whitespace-only lines
@@ -293,7 +313,30 @@ index 8d44b5f..2f4e25f 100644
      moveInfo[@"AXTextSelectionGranularity"] = @(granularity);
  
    ns_ax_post_notification_with_info (
-@@ -9175,6 +9303,7 @@ - (void)postCompletionAnnouncementForBuffer:(struct buffer *)b
+@@ -9107,12 +9235,17 @@ derive its own speech (it would read the wrong character
+ 	}
+     }
+ 
+-  /* For focused line moves: always announce line text explicitly.
+-     SelectedTextChanged with granularity=line works for arrow keys,
+-     but C-n/C-p need the explicit announcement (VoiceOver processes
+-     these keystrokes differently from arrows).
++  /* Announce the destination line text for all line-granularity moves.
++     This covers two cases:
++     - C-n/C-p: SelectedTextChanged carries granularity=line, but
++       VoiceOver processes those keystrokes specially and may not
++       produce speech; the explicit announcement is the reliable path.
++     - Discontiguous jumps (]], M-<, xref, imenu, …): granularity=line
++       in the notification is omitted (see above) so VoiceOver will
++       not announce automatically; this explicit announcement fills
++       the gap.
+      In completion-list-mode, read the completion candidate instead
+-     of the whole line.  */
++     of the full line.  */
+   if (cachedText
+       && granularity == ns_ax_text_selection_granularity_line)
+     {
+@@ -9175,6 +9308,7 @@ - (void)postCompletionAnnouncementForBuffer:(struct buffer *)b
    ptrdiff_t currentOverlayStart = 0;
    ptrdiff_t currentOverlayEnd = 0;
  
@@ -301,7 +344,7 @@ index 8d44b5f..2f4e25f 100644
    specpdl_ref count2 = SPECPDL_INDEX ();
    record_unwind_current_buffer ();
    if (b != current_buffer)
-@@ -9352,6 +9481,61 @@ - (void)postAccessibilityNotificationsForFrame:(struct frame *)f
+@@ -9352,6 +9486,66 @@ - (void)postAccessibilityNotificationsForFrame:(struct frame *)f
    if (!b)
      return;
  
@@ -329,6 +372,11 @@ index 8d44b5f..2f4e25f 100644
 +	{
 +	  struct buffer *eb = XBUFFER (ea);
 +	  ptrdiff_t echo_chars = BUF_CHARS_MODIFF (eb);
++	  /* cachedCharsModiff doubles as echo-area change detector.
++	     For an inactive minibuffer element this ivar is only written
++	     here, so comparing the echo buffer's chars_modiff against it
++	     reliably detects new messages.  Both are ptrdiff_t counters
++	     that increase monotonically; a false negative is impossible.  */
 +	  if (echo_chars != self.cachedCharsModiff
 +	      && BUF_ZV (eb) > BUF_BEGV (eb))
 +	    {
@@ -363,7 +411,7 @@ index 8d44b5f..2f4e25f 100644
    ptrdiff_t modiff = BUF_MODIFF (b);
    ptrdiff_t point = BUF_PT (b);
    BOOL markActive = !NILP (BVAR (b, mark_active));
-@@ -9488,6 +9672,16 @@ frameworks like Vertico bump BOTH BUF_MODIFF (via text property
+@@ -9488,6 +9682,16 @@ frameworks like Vertico bump BOTH BUF_MODIFF (via text property
  	  granularity = ns_ax_text_selection_granularity_line;
  	}
  
@@ -380,7 +428,7 @@ index 8d44b5f..2f4e25f 100644
        /* Post notifications for focused and non-focused elements.  */
        if ([self isAccessibilityFocused])
  	[self postFocusedCursorNotification:point
-@@ -9931,6 +10125,10 @@ - (void)dealloc
+@@ -9931,6 +10135,10 @@ - (void)dealloc
  #endif
  
    [accessibilityElements release];
@@ -391,7 +439,7 @@ index 8d44b5f..2f4e25f 100644
    [[self menu] release];
    [super dealloc];
  }
-@@ -11380,6 +11578,9 @@ - (instancetype) initFrameFromEmacs: (struct frame *)f
+@@ -11380,6 +11588,9 @@ - (instancetype) initFrameFromEmacs: (struct frame *)f
  
    windowClosing = NO;
    processingCompose = NO;
@@ -401,7 +449,7 @@ index 8d44b5f..2f4e25f 100644
    scrollbarsNeedingUpdate = 0;
    fs_state = FULLSCREEN_NONE;
    fs_before_fs = next_maximized = -1;
-@@ -12688,6 +12889,80 @@ - (id)accessibilityFocusedUIElement
+@@ -12688,6 +12899,80 @@ - (id)accessibilityFocusedUIElement
     The existing elements carry cached state (modiff, point) from the
     previous redisplay cycle.  Rebuilding first would create fresh
     elements with current values, making change detection impossible.  */
@@ -482,7 +530,7 @@ index 8d44b5f..2f4e25f 100644
  - (void)postAccessibilityUpdates
  {
    NSTRACE ("[EmacsView postAccessibilityUpdates]");
-@@ -12698,11 +12973,59 @@ - (void)postAccessibilityUpdates
+@@ -12698,11 +12983,59 @@ - (void)postAccessibilityUpdates
  
    /* Re-entrance guard: VoiceOver callbacks during notification posting
       can trigger redisplay, which calls ns_update_end, which calls us