patches: split VoiceOver into 3-patch series, improve docs

Split the monolithic 3011-line patch into logical pieces:
  0001: All new accessibility code (infrastructure, no existing code modified)
  0002: EmacsView integration + cursor tracking (wiring only)
  0003: Documentation (expanded with known limitations)

Improvements:
- Comprehensive commit messages with testing methodology
- Known limitations documented (text cap, bidi, mode-line icons)
- Documentation expanded with Known Limitations section
- Each patch is self-contained and reviewable

patches/0002-ns-integrate-accessibility-with-EmacsView-and-cursor.patch

@@ -0,0 +1,481 @@
+From 92b00024559ff35a61d34f85e2c048a1845fca99 Mon Sep 17 00:00:00 2001
+From: Martin Sukany <martin@sukany.cz>
+Date: Sat, 28 Feb 2026 09:32:52 +0100
+Subject: [PATCH 2/3] ns: integrate accessibility with EmacsView and cursor
+ tracking
+
+Wire the accessibility infrastructure from the previous patch into
+the existing EmacsView class and the redisplay cycle.  After this
+patch, VoiceOver and Zoom support is fully active.
+
+Integration points:
+
+  ns_update_end: call [view postAccessibilityUpdates] after each
+  redisplay cycle to dispatch accessibility notifications.
+
+  ns_draw_phys_cursor: store cursor rect for Zoom and call
+  UAZoomChangeFocus with correct CG coordinate-space transform
+  when ns-accessibility-enabled is non-nil.
+
+  EmacsView dealloc: release accessibilityElements array.
+
+  EmacsView windowDidBecomeKey: post
+  FocusedUIElementChangedNotification and SelectedTextChanged
+  so VoiceOver tracks the focused buffer on app/window switch.
+
+  EmacsView accessibility methods: rebuildAccessibilityTree walks
+  the Emacs window tree (ns_ax_collect_windows) to create/reuse
+  virtual elements.  accessibilityChildren, accessibilityFocusedUI-
+  Element, postAccessibilityUpdates (the main notification dispatch
+  loop), accessibilityBoundsForRange (delegates to focused buffer
+  element with cursor-rect fallback for Zoom), and legacy
+  parameterized attribute APIs.
+
+  postAccessibilityUpdates detects three events: window tree change
+  (rebuild + layout notification), window switch (focus notification),
+  and per-buffer changes (delegated to each buffer element).  A
+  re-entrance guard prevents infinite recursion from VoiceOver
+  callbacks that trigger redisplay.
+
+* src/nsterm.m: EmacsView accessibility integration.
+---
+ src/nsterm.m | 395 +++++++++++++++++++++++++++++++++++++++++++++++++++
+ 1 file changed, 395 insertions(+)
+
+diff --git a/src/nsterm.m b/src/nsterm.m
+index c47912d..34af842 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];
+@@ -9204,6 +9246,7 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem,
+   [layer release];
+ #endif
+ 
++  [accessibilityElements release];
+   [[self menu] release];
+   [super dealloc];
+ }
+@@ -10552,6 +10595,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
+ }
+ 
+ 
+@@ -11789,6 +11858,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
+