patches: 5-patch VoiceOver series (improved split + safety docs)

Split into 5 logical patches:
  0001: Base classes + text extraction (+474)
  0002: Buffer + ModeLine protocol (+1620)
  0003: Interactive spans (+403)
  0004: EmacsView integration + etc/NEWS (+408)
  0005: Documentation (+75)

Improvements over previous version:
- 5 patches (was 3): finer granularity
- Helpers placed in correct patches (find_completion_overlay_range,
  event_is_line_nav_key moved to patch with their users)
- etc/NEWS moved to last functional patch (0004)
- ChangeLog-format commit messages
- Longjmp safety analysis comment in code
- Code reorganized for clean sequential patches

patches/0004-ns-integrate-accessibility-with-EmacsView-and-redisp.patch

@@ -0,0 +1,508 @@
+From 9ec896a226144676a36908938899fc90c2f5730b Mon Sep 17 00:00:00 2001
+From: Martin Sukany <martin@sukany.cz>
+Date: Sat, 28 Feb 2026 10:10:55 +0100
+Subject: [PATCH 4/5] ns: integrate accessibility with EmacsView and redisplay
+
+Wire the accessibility infrastructure into EmacsView and the
+redisplay cycle.
+
+* src/nsterm.m (ns_update_end): Call [view postAccessibilityUpdates].
+(ns_draw_phys_cursor): Store cursor rect; call UAZoomChangeFocus.
+(EmacsView dealloc): Release accessibilityElements.
+(EmacsView windowDidBecomeKey): Post FocusedUIElementChanged and
+SelectedTextChanged.
+(ns_ax_collect_windows): New function.  Walk window tree creating
+virtual elements.
+(EmacsView rebuildAccessibilityTree): New method.
+(EmacsView invalidateAccessibilityTree): New method.
+(EmacsView accessibilityChildren): New method.
+(EmacsView accessibilityFocusedUIElement): New method.
+(EmacsView postAccessibilityUpdates): New method.  Detect tree
+change, window switch, per-buffer changes; re-entrance guard.
+(EmacsView accessibilityBoundsForRange:): New method.  Cursor rect
+for Zoom with focused-element delegation.
+(EmacsView accessibilityParameterizedAttributeNames): New method.
+(EmacsView accessibilityAttributeValue:forParameter:): New method.
+* etc/NEWS: Document VoiceOver accessibility support.
+---
+ etc/NEWS     |  13 ++
+ src/nsterm.m | 397 ++++++++++++++++++++++++++++++++++++++++++++++++++-
+ 2 files changed, 408 insertions(+), 2 deletions(-)
+
+diff --git a/etc/NEWS b/etc/NEWS
+index 7367e3c..608650e 100644
+--- a/etc/NEWS
++++ b/etc/NEWS
+@@ -4374,6 +4374,19 @@ allowing Emacs users access to speech recognition utilities.
+ Note: Accepting this permission allows the use of system APIs, which may
+ 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
++(buttons, links, completion candidates), and completion announcements
++for the *Completions* buffer.  The implementation uses a virtual
++accessibility tree with per-window elements, hybrid SelectedTextChanged
++and AnnouncementRequested notifications, and thread-safe text caching.
++Set 'ns-accessibility-enabled' to nil to disable the accessibility
++interface and eliminate the associated overhead.
++
+ ---
+ ** Re-introduced dictation, lost in Emacs v30 (macOS).
+ We lost macOS dictation in v30 when migrating to NSTextInputClient.
+diff --git a/src/nsterm.m b/src/nsterm.m
+index db5e4b3..421a6a4 100644
+--- a/src/nsterm.m
++++ b/src/nsterm.m
+@@ -1105,6 +1105,11 @@ ns_update_end (struct frame *f)
+ 
+   unblock_input ();
+   ns_updating_frame = NULL;
++
++#ifdef NS_IMPL_COCOA
++  /* Post accessibility notifications after each redisplay cycle.  */
++  [view postAccessibilityUpdates];
++#endif
+ }
+ 
+ static void
+@@ -3233,6 +3238,43 @@ ns_draw_window_cursor (struct window *w, struct glyph_row *glyph_row,
+   /* Prevent the cursor from being drawn outside the text area.  */
+   r = NSIntersectionRect (r, ns_row_rect (w, glyph_row, TEXT_AREA));
+ 
++#ifdef NS_IMPL_COCOA
++  /* Accessibility: store cursor rect for Zoom and bounds queries.
++     Skipped when ns-accessibility-enabled is nil to avoid overhead.
++     VoiceOver notifications are handled solely by
++     postAccessibilityUpdates (called from ns_update_end)
++     to avoid duplicate notifications and mid-redisplay fragility.  */
++  {
++    EmacsView *view = FRAME_NS_VIEW (f);
++    if (view && on_p && active_p && ns_accessibility_enabled)
++      {
++	view->lastAccessibilityCursorRect = r;
++
++	/* Tell macOS Zoom where the cursor is.  UAZoomChangeFocus()
++	   expects top-left origin (CG coordinate space).
++	   These APIs are available since macOS 10.4 (Universal Access
++	   framework, linked via ApplicationServices umbrella).  */
++#if defined (MAC_OS_X_VERSION_MIN_REQUIRED) \
++    && MAC_OS_X_VERSION_MIN_REQUIRED >= 101000
++	if (UAZoomEnabled ())
++	  {
++	    NSRect windowRect = [view convertRect:r toView:nil];
++	    NSRect screenRect = [[view window] convertRectToScreen:windowRect];
++	    CGRect cgRect = NSRectToCGRect (screenRect);
++
++	    CGFloat primaryH
++	      = [[[NSScreen screens] firstObject] frame].size.height;
++	    cgRect.origin.y
++	      = primaryH - cgRect.origin.y - cgRect.size.height;
++
++	    UAZoomChangeFocus (&cgRect, &cgRect,
++			       kUAZoomFocusTypeInsertionPoint);
++	  }
++#endif /* MAC_OS_X_VERSION_MIN_REQUIRED >= 101000 */
++      }
++  }
++#endif
++
+   ns_focus (f, NULL, 0);
+ 
+   NSGraphicsContext *ctx = [NSGraphicsContext currentContext];
+@@ -7180,7 +7222,6 @@ enum {
+ 
+ 
+ 
+-
+ static BOOL
+ ns_ax_find_completion_overlay_range (struct buffer *b, ptrdiff_t point,
+ 				     ptrdiff_t *out_start,
+@@ -8798,7 +8839,6 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem,
+ @end
+ 
+ 
+-
+ /* ===================================================================
+    EmacsAccessibilityInteractiveSpan — helpers and implementation
+    =================================================================== */
+@@ -9245,6 +9285,7 @@ ns_ax_scan_interactive_spans (struct window *w,
+   [layer release];
+ #endif
+ 
++  [accessibilityElements release];
+   [[self menu] release];
+   [super dealloc];
+ }
+@@ -10593,6 +10634,32 @@ ns_in_echo_area (void)
+   XSETFRAME (event.frame_or_window, emacsframe);
+   kbd_buffer_store_event (&event);
+   ns_send_appdefined (-1);  // Kick main loop
++
++#ifdef NS_IMPL_COCOA
++  /* Notify VoiceOver that the focused accessibility element changed.
++     Post on the focused virtual element so VoiceOver starts tracking it.
++     This is critical for initial focus and app-switch scenarios.  */
++  if (ns_accessibility_enabled)
++  {
++    id focused = [self accessibilityFocusedUIElement];
++    if (focused
++	&& [focused isKindOfClass:[EmacsAccessibilityBuffer class]])
++      {
++	ns_ax_post_notification (focused,
++	  NSAccessibilityFocusedUIElementChangedNotification);
++	NSDictionary *info = @{
++	    @"AXTextStateChangeType":
++	      @(ns_ax_text_state_change_selection_move),
++	    @"AXTextChangeElement": focused
++	  };
++	ns_ax_post_notification_with_info (focused,
++	  NSAccessibilitySelectedTextChangedNotification, info);
++      }
++    else if (focused)
++      ns_ax_post_notification (focused,
++	NSAccessibilityFocusedUIElementChangedNotification);
++  }
++#endif
+ }
+ 
+ 
+@@ -11830,6 +11897,332 @@ ns_in_echo_area (void)
+   return fs_state;
+ }
+ 
++#ifdef NS_IMPL_COCOA
++
++/* ---- Accessibility: walk the Emacs window tree ---- */
++
++static void
++ns_ax_collect_windows (Lisp_Object window, EmacsView *view,
++		       NSMutableArray *elements,
++		       NSDictionary *existing)
++{
++  if (NILP (window))
++    return;
++
++  struct window *w = XWINDOW (window);
++
++  if (WINDOW_LEAF_P (w))
++    {
++      /* Buffer element — reuse existing if available.  */
++      EmacsAccessibilityBuffer *elem
++	= [existing objectForKey:[NSValue valueWithPointer:w]];
++      if (!elem)
++	{
++	  elem = [[EmacsAccessibilityBuffer alloc] init];
++	  elem.emacsView = view;
++
++	  /* Initialize cached state to -1 to force first notification.  */
++	  elem.cachedModiff = -1;
++	  elem.cachedPoint = -1;
++	  elem.cachedMarkActive = NO;
++	}
++      else
++	{
++	  [elem retain];
++	}
++      elem.lispWindow = window;
++      [elements addObject:elem];
++      [elem release];
++
++      /* Mode line element (skip for minibuffer).  */
++      if (!MINI_WINDOW_P (w))
++	{
++	  EmacsAccessibilityModeLine *ml
++	    = [[EmacsAccessibilityModeLine alloc] init];
++	  ml.emacsView = view;
++	  ml.lispWindow = window;
++	  [elements addObject:ml];
++	  [ml release];
++	}
++    }
++  else
++    {
++      /* Internal (combination) window — recurse into children.  */
++      Lisp_Object child = w->contents;
++      while (!NILP (child))
++	{
++	  ns_ax_collect_windows (child, view, elements, existing);
++	  child = XWINDOW (child)->next;
++	}
++    }
++}
++
++- (void)rebuildAccessibilityTree
++{
++  NSTRACE ("[EmacsView rebuildAccessibilityTree]");
++  if (!emacsframe)
++    return;
++
++  /* Build map of existing elements by window pointer for reuse.  */
++  NSMutableDictionary *existing = [NSMutableDictionary dictionary];
++  if (accessibilityElements)
++    {
++      for (EmacsAccessibilityElement *elem in accessibilityElements)
++	{
++	  if ([elem isKindOfClass:[EmacsAccessibilityBuffer class]]
++	      && !NILP (elem.lispWindow))
++	    [existing setObject:elem
++			 forKey:[NSValue valueWithPointer:
++				  XWINDOW (elem.lispWindow)]];
++	}
++    }
++
++  NSMutableArray *newElements = [NSMutableArray arrayWithCapacity:8];
++
++  /* Collect from main window tree.  */
++  Lisp_Object root = FRAME_ROOT_WINDOW (emacsframe);
++  ns_ax_collect_windows (root, self, newElements, existing);
++
++  /* Include minibuffer.  */
++  Lisp_Object mini = emacsframe->minibuffer_window;
++  if (!NILP (mini))
++    ns_ax_collect_windows (mini, self, newElements, existing);
++
++  [accessibilityElements release];
++  accessibilityElements = [newElements retain];
++  accessibilityTreeValid = YES;
++}
++
++- (void)invalidateAccessibilityTree
++{
++  accessibilityTreeValid = NO;
++}
++
++- (NSAccessibilityRole)accessibilityRole
++{
++  return NSAccessibilityGroupRole;
++}
++
++- (NSString *)accessibilityLabel
++{
++  return @"Emacs";
++}
++
++- (BOOL)isAccessibilityElement
++{
++  return YES;
++}
++
++- (NSArray *)accessibilityChildren
++{
++  if (!accessibilityElements || !accessibilityTreeValid)
++    [self rebuildAccessibilityTree];
++  return accessibilityElements;
++}
++
++- (id)accessibilityFocusedUIElement
++{
++  if (!emacsframe)
++    return self;
++
++  if (!accessibilityElements || !accessibilityTreeValid)
++    [self rebuildAccessibilityTree];
++
++  for (EmacsAccessibilityElement *elem in accessibilityElements)
++    {
++      if ([elem isKindOfClass:[EmacsAccessibilityBuffer class]]
++	  && EQ (elem.lispWindow, emacsframe->selected_window))
++	return elem;
++    }
++  return self;
++}
++
++/* Called from ns_update_end to post AX notifications.
++
++   Important: post notifications BEFORE rebuilding the tree.
++   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.  */
++- (void)postAccessibilityUpdates
++{
++  NSTRACE ("[EmacsView postAccessibilityUpdates]");
++  eassert ([NSThread isMainThread]);
++
++  if (!emacsframe || !ns_accessibility_enabled)
++    return;
++
++  /* Re-entrance guard: VoiceOver callbacks during notification posting
++     can trigger redisplay, which calls ns_update_end, which calls us
++     again.  Prevent infinite recursion.  */
++  if (accessibilityUpdating)
++    return;
++  accessibilityUpdating = YES;
++
++  /* Detect window tree change (split, delete, new buffer).  Compare
++     FRAME_ROOT_WINDOW — if it changed, the tree structure changed.  */
++  Lisp_Object curRoot = FRAME_ROOT_WINDOW (emacsframe);
++  if (!EQ (curRoot, lastRootWindow))
++    {
++      lastRootWindow = curRoot;
++      accessibilityTreeValid = NO;
++    }
++
++  /* If tree is stale, rebuild FIRST so we don't iterate freed
++     window pointers.  Skip notifications for this cycle — the
++     freshly-built elements have no previous state to diff against.  */
++  if (!accessibilityTreeValid)
++    {
++      [self rebuildAccessibilityTree];
++      /* Invalidate span cache — window layout changed.  */
++      for (EmacsAccessibilityElement *elem in accessibilityElements)
++	if ([elem isKindOfClass: [EmacsAccessibilityBuffer class]])
++	  [(EmacsAccessibilityBuffer *) elem invalidateInteractiveSpans];
++      ns_ax_post_notification (self,
++	NSAccessibilityLayoutChangedNotification);
++
++      /* Post focus change so VoiceOver picks up the new tree.  */
++      id focused = [self accessibilityFocusedUIElement];
++      if (focused && focused != self)
++	ns_ax_post_notification (focused,
++	  NSAccessibilityFocusedUIElementChangedNotification);
++
++      lastSelectedWindow = emacsframe->selected_window;
++      accessibilityUpdating = NO;
++      return;
++    }
++
++  /* Post per-buffer notifications using EXISTING elements that have
++     cached state from the previous cycle.  Validate each window
++     pointer before use.  */
++  for (EmacsAccessibilityElement *elem in accessibilityElements)
++    {
++      if ([elem isKindOfClass:[EmacsAccessibilityBuffer class]])
++	{
++	  struct window *w = [elem validWindow];
++	  if (w && WINDOW_LEAF_P (w)
++	      && BUFFERP (w->contents) && XBUFFER (w->contents))
++	    [(EmacsAccessibilityBuffer *) elem
++	       postAccessibilityNotificationsForFrame:emacsframe];
++	}
++    }
++
++  /* Check for window switch (C-x o).  */
++  Lisp_Object curSel = emacsframe->selected_window;
++  BOOL windowSwitched = !EQ (curSel, lastSelectedWindow);
++  if (windowSwitched)
++    {
++      lastSelectedWindow = curSel;
++      id focused = [self accessibilityFocusedUIElement];
++      if (focused && focused != self
++	  && [focused isKindOfClass:[EmacsAccessibilityBuffer class]])
++	{
++	  ns_ax_post_notification (focused,
++	    NSAccessibilityFocusedUIElementChangedNotification);
++	  NSDictionary *info = @{
++	    @"AXTextStateChangeType":
++	      @(ns_ax_text_state_change_selection_move),
++	    @"AXTextChangeElement": focused
++	  };
++	  ns_ax_post_notification_with_info (focused,
++	    NSAccessibilitySelectedTextChangedNotification, info);
++	}
++      else if (focused && focused != self)
++	ns_ax_post_notification (focused,
++	  NSAccessibilityFocusedUIElementChangedNotification);
++    }
++
++  accessibilityUpdating = NO;
++}
++
++/* ---- Cursor position for Zoom (via accessibilityBoundsForRange:) ----
++
++   accessibilityFrame returns the VIEW's frame (standard behavior).
++   The cursor location is exposed through accessibilityBoundsForRange:
++   which AT tools query using the selectedTextRange.  */
++
++- (NSRect)accessibilityBoundsForRange:(NSRange)range
++{
++  /* Delegate to the focused buffer element for accurate per-range
++     geometry when possible.  Fall back to the cached cursor rect
++     (set by ns_draw_phys_cursor) for Zoom and simple AT queries.  */
++  id focused = [self accessibilityFocusedUIElement];
++  if ([focused isKindOfClass:[EmacsAccessibilityBuffer class]])
++    {
++      NSRect bufRect = [(EmacsAccessibilityBuffer *) focused
++			 accessibilityFrameForRange:range];
++      if (!NSIsEmptyRect (bufRect))
++	return bufRect;
++    }
++
++  NSRect viewRect = lastAccessibilityCursorRect;
++
++  if (viewRect.size.width < 1)
++    viewRect.size.width = 1;
++  if (viewRect.size.height < 1)
++    viewRect.size.height = 8;
++
++  NSWindow *win = [self window];
++  if (win == nil)
++    return NSZeroRect;
++
++  NSRect windowRect = [self convertRect:viewRect toView:nil];
++  return [win convertRectToScreen:windowRect];
++}
++
++/* Modern NSAccessibility protocol entry point.  Delegates to
++   accessibilityBoundsForRange: which holds the real implementation
++   shared with the legacy parameterized-attribute API.  */
++- (NSRect)accessibilityFrameForRange:(NSRange)range
++{
++  return [self accessibilityBoundsForRange:range];
++}
++
++/* Delegate to the focused virtual buffer element so both the modern
++   and legacy APIs return the correct string data.  */
++- (NSString *)accessibilityStringForRange:(NSRange)range
++{
++  id focused = [self accessibilityFocusedUIElement];
++  if ([focused isKindOfClass:[EmacsAccessibilityBuffer class]])
++    return [(EmacsAccessibilityBuffer *) focused
++	     accessibilityStringForRange:range];
++  return @"";
++}
++
++/* ---- Legacy parameterized attribute APIs (Zoom uses these) ---- */
++
++- (NSArray *)accessibilityParameterizedAttributeNames
++{
++  NSArray *superAttrs = [super accessibilityParameterizedAttributeNames];
++  if (superAttrs == nil)
++    superAttrs = @[];
++  return [superAttrs arrayByAddingObjectsFromArray:
++	    @[NSAccessibilityBoundsForRangeParameterizedAttribute,
++	      NSAccessibilityStringForRangeParameterizedAttribute]];
++}
++
++- (id)accessibilityAttributeValue:(NSString *)attribute
++		     forParameter:(id)parameter
++{
++  if ([attribute isEqualToString:
++	 NSAccessibilityBoundsForRangeParameterizedAttribute])
++    {
++      NSRange range = [(NSValue *) parameter rangeValue];
++      return [NSValue valueWithRect:
++		[self accessibilityBoundsForRange:range]];
++    }
++
++  if ([attribute isEqualToString:
++	 NSAccessibilityStringForRangeParameterizedAttribute])
++    {
++      NSRange range = [(NSValue *) parameter rangeValue];
++      return [self accessibilityStringForRange:range];
++    }
++
++  return [super accessibilityAttributeValue:attribute forParameter:parameter];
++}
++
++#endif /* NS_IMPL_COCOA */
++
+ @end  /* EmacsView */
+ 
+ 
+-- 
+2.43.0
+