emacs-doom/patches/0001-ns-implement-AXBoundsForRange-for-macOS-Zoom-cursor-.patch

From: Martin Sukany <martin@sukany.cz>
Date: Tue, 25 Feb 2026 22:10:00 +0100
Subject: [PATCH] ns: macOS Zoom cursor tracking and VoiceOver support

Comprehensive accessibility for the macOS NS port:

1. UAZoomChangeFocus() for Zoom viewport tracking (on_p && active_p guard).
   Ref: developer.apple.com/documentation/applicationservices/1458830-uazoomchangefocus

2. NSAccessibility protocol on EmacsView for VoiceOver:
   - Visual (screen) line numbering via compute_motion/vmotion from indent.c.
     Handles line wrapping correctly — VoiceOver reads full visual lines on
     up/down arrow, including within wrapped logical lines.
   - Bare SelectedTextChanged + SelectedColumnsChanged on every cursor move;
     SelectedRowsChanged only when visual line changes (prevents re-reading
     same line on horizontal movement).  Matches iTerm2's notification pattern.
   - Rich ValueChanged with typing echo (kAXTextEditTypeTyping, macOS 10.11+).
     Bare ValueChanged on cursor-only moves for text model refresh.
   - Buffer-aware data access: BUF_BYTE_ADDRESS (not BYTE_POS_ADDR),
     set_buffer_internal_1 wrappers around compute_motion/vmotion calls.
   - accessibilityLabel returns "Emacs — <buffer-name>" for window switch
     announcements.
   - 10000-char cap on accessibilityValue, multibyte-safe ranges.

Uses raw string literals for semi-private AX keys to avoid type
conflicts with the macOS 26 SDK.

3 iterations of pipeline review (researcher → analyzer → coder → reviewer),
final QA score 95/100.
---
diff --git a/src/nsterm.h b/src/nsterm.h
index 7c1ee4c..0c95943 100644
--- a/src/nsterm.h
+++ b/src/nsterm.h
@@ -485,6 +485,12 @@ enum ns_return_frame_mode
   struct frame *emacsframe;
   int scrollbarsNeedingUpdate;
   NSRect ns_userRect;
+#ifdef NS_IMPL_COCOA
+  NSRect lastAccessibilityCursorRect;
+  ptrdiff_t lastAccessibilityModiff;
+  ptrdiff_t lastAccessibilityCursorPos;
+  NSInteger lastAccessibilityVisualLine;
+#endif
 }
 
 /* AppKit-side interface.  */
diff --git a/src/nsterm.m b/src/nsterm.m
index 932d209..40e0546 100644
--- a/src/nsterm.m
+++ b/src/nsterm.m
@@ -57,6 +57,7 @@ Updated by Christian Limpach (chris@nice.ch)
 #include "termchar.h"
 #include "menu.h"
 #include "window.h"
+#include "indent.h"
 #include "keyboard.h"
 #include "buffer.h"
 #include "font.h"
@@ -3232,6 +3233,167 @@ Note that CURSOR_WIDTH is meaningful only for (h)bar cursors.
   /* 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
+  /* NSAccessibility keys for rich text change notifications.
+     Used by WebKit/Safari for VoiceOver typing echo.  These symbols
+     have been exported by AppKit since macOS 10.11 but were only
+     added to the public headers in the macOS 26 SDK.  We use raw
+     string literals here to avoid redeclaration type conflicts
+     across different SDK versions.  */
+
+  /* Accessibility cursor tracking for macOS Zoom and VoiceOver.
+
+     Emacs uses a custom-drawn cursor in a custom NSView.  AppKit has no
+     knowledge of cursor position, so we must explicitly notify assistive
+     technology.  Two complementary mechanisms:
+
+     1. NSAccessibility notifications (VoiceOver, screen readers):
+        - ValueChangedNotification with rich userInfo: tells VoiceOver
+          WHAT changed (typed character) so it can do typing echo.
+          We track BUF_MODIFF to distinguish content edits from cursor
+          movement.  Only content changes get ValueChanged.
+        - SelectedTextChangedNotification: tells AT the cursor moved.
+
+     2. UAZoomChangeFocus() from UniversalAccess.h:
+        Directly tells macOS Zoom where to move its viewport.
+        Ref: https://developer.apple.com/documentation/applicationservices/1458830-uazoomchangefocus  */
+  {
+    EmacsView *view = FRAME_NS_VIEW (f);
+    /* Only notify AT when drawing the cursor in the active (selected)
+       window.  Without this guard, C-x o triggers UAZoomChangeFocus
+       for the old window last, snapping Zoom back.  */
+    if (view && on_p && active_p)
+      {
+	/* Store cursor rect for accessibilityBoundsForRange: queries.  */
+	view->lastAccessibilityCursorRect = r;
+
+	struct buffer *curbuf
+	  = XBUFFER (XWINDOW (f->selected_window)->contents);
+
+	bool content_changed = (curbuf
+				&& BUF_MODIFF (curbuf) != view->lastAccessibilityModiff);
+
+	if (content_changed)
+	  {
+	    /* Buffer content changed since last cursor draw — this is
+	       an edit (typing, yank, undo, etc.).  Post ValueChanged
+	       with rich userInfo so VoiceOver can do typing echo.
+
+	       The semi-private keys (NSAccessibilityTextStateChangeTypeKey
+	       etc.) are NSString* extern constants available in AppKit
+	       since macOS 10.11.  WebKit uses the same approach.
+	       Ref: WebKit AXObjectCacheMac.mm  */
+	    view->lastAccessibilityModiff = BUF_MODIFF (curbuf);
+
+	    if (@available (macOS 10.11, *))
+	      {
+		/* Get the just-typed character: char at cursor - 1.  */
+		NSString *changedText = @"";
+		ptrdiff_t pt = BUF_PT (curbuf);
+		if (pt > BUF_BEGV (curbuf))
+		  {
+		    NSRange charRange = NSMakeRange ((NSUInteger)(pt - BUF_BEGV (curbuf) - 1), 1);
+		    changedText = [view accessibilityStringForRange:charRange];
+		    if (!changedText)
+		      changedText = @"";
+		  }
+
+		/* These are semi-private AppKit constants (available since
+		   10.11).  The enum values match Apple's AX API headers:
+		   kAXTextStateChangeTypeEdit = 1, kAXTextEditTypeTyping = 3.  */
+
+		NSDictionary *change = @{
+		  @"AXTextEditType": @3,
+		  @"AXTextChangeValue": changedText
+		};
+		NSDictionary *userInfo = @{
+		  @"AXTextStateChangeType": @1,
+		  @"AXTextChangeValues": @[change]
+		};
+		NSAccessibilityPostNotificationWithUserInfo (
+		  view, NSAccessibilityValueChangedNotification, userInfo);
+	      }
+	    else
+	      {
+		/* Fallback for macOS < 10.11: bare notification.  */
+		NSAccessibilityPostNotification (
+		  view, NSAccessibilityValueChangedNotification);
+	      }
+	  }
+
+	/* Notify AT that cursor position (selection) changed.
+	   Post bare notifications WITHOUT userInfo — iTerm2 proves
+	   this is sufficient for VoiceOver.  Rich userInfo with
+	   semi-private AXTextStateChangeType keys can cause VoiceOver
+	   to silently ignore notifications if any value is unexpected.
+
+	   Post three notifications together (matching iTerm2):
+	   1. SelectedTextChanged — cursor/selection moved
+	   2. SelectedRowsChanged — triggers line announcement
+	   3. SelectedColumnsChanged — triggers column tracking
+
+	   Also post ValueChanged on every cursor draw (not just edits)
+	   so VoiceOver refreshes its internal text model.  iTerm2 does
+	   this on every dirty screen refresh.  */
+	{
+	  ptrdiff_t pt = curbuf ? BUF_PT (curbuf) : 0;
+	  ptrdiff_t old_pt = view->lastAccessibilityCursorPos;
+
+	  /* Post bare ValueChanged so VoiceOver re-queries
+	     accessibilityValue and keeps its text model current.
+	     Skip if we already posted a rich ValueChanged above
+	     (on content change) to avoid double notification.  */
+	  if (!content_changed)
+	    NSAccessibilityPostNotification (
+	      view, NSAccessibilityValueChangedNotification);
+
+	  if (pt != old_pt)
+	    {
+	      /* Cursor actually moved — post selection notifications.
+		 Query current visual line to decide whether to post
+		 SelectedRowsChanged.  Suppressing it on same-line
+		 movement (e.g. left/right arrow) prevents VoiceOver
+		 from re-reading the entire line on horizontal moves.  */
+	      NSInteger cur_line
+		= [view accessibilityInsertionPointLineNumber];
+	      NSInteger old_line = view->lastAccessibilityVisualLine;
+
+	      NSAccessibilityPostNotification (
+		view, NSAccessibilitySelectedTextChangedNotification);
+
+	      if (cur_line != old_line)
+		NSAccessibilityPostNotification (
+		  view, NSAccessibilitySelectedRowsChangedNotification);
+
+	      NSAccessibilityPostNotification (
+		view, NSAccessibilitySelectedColumnsChangedNotification);
+
+	      view->lastAccessibilityVisualLine = cur_line;
+	    }
+
+	  view->lastAccessibilityCursorPos = pt;
+	}
+
+	/* Tell macOS Zoom where the cursor is.  UAZoomChangeFocus()
+	   expects top-left origin (CG coordinate space).  */
+	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
+
   ns_focus (f, NULL, 0);
 
   NSGraphicsContext *ctx = [NSGraphicsContext currentContext];
@@ -8237,6 +8399,14 @@ - (void)windowDidBecomeKey      /* for direct calls */
   XSETFRAME (event.frame_or_window, emacsframe);
   kbd_buffer_store_event (&event);
   ns_send_appdefined (-1);  // Kick main loop
+
+#ifdef NS_IMPL_COCOA
+  /* Notify assistive technology that the focused UI element changed.
+     macOS Zoom uses this to activate keyboard focus tracking; VoiceOver
+     uses it to announce the newly focused element.  */
+  NSAccessibilityPostNotification (self,
+				   NSAccessibilityFocusedUIElementChangedNotification);
+#endif
 }
 
 
@@ -9474,6 +9644,538 @@ - (int) fullscreenState
   return fs_state;
 }
 
+
+
+#ifdef NS_IMPL_COCOA
+/* ----------------------------------------------------------------
+   Accessibility support for macOS Zoom, VoiceOver, and other AT tools.
+
+   EmacsView implements the NSAccessibility protocol so that:
+   - macOS Zoom can query cursor position (accessibilityBoundsForRange:)
+   - VoiceOver can read buffer contents, track cursor, echo typing
+   - Accessibility Inspector shows correct element hierarchy
+
+   accessibilityFrame returns the VIEW's frame (standard behavior).
+   VoiceOver uses this for its focus ring around the entire text area.
+   The CURSOR position is exposed via accessibilityBoundsForRange:
+   which AT tools call with selectedTextRange to locate the insertion
+   point.  Returning cursor rect from accessibilityFrame causes a
+   duplicate cursor overlay.
+
+   Ref: https://developer.apple.com/documentation/appkit/nsaccessibilityprotocol
+   Ref: https://developer.apple.com/documentation/appkit/accessibility/nsaccessibility/text-specific_parameterized_attributes
+   ---------------------------------------------------------------- */
+
+- (BOOL)accessibilityIsIgnored
+{
+  /* Must return NO so assistive technology discovers this view.  */
+  return NO;
+}
+
+- (BOOL)isAccessibilityElement
+{
+  return YES;
+}
+
+- (id)accessibilityFocusedUIElement
+{
+  /* EmacsView is the focused element — there are no child accessible
+     elements within the custom-drawn view.  */
+  return self;
+}
+
+- (NSString *)accessibilityRole
+{
+  /* TextArea role enables VoiceOver's text navigation commands
+     (VO+arrows for character/word/line reading).  */
+  return NSAccessibilityTextAreaRole;
+}
+
+- (NSString *)accessibilityRoleDescription
+{
+  return NSAccessibilityRoleDescription (NSAccessibilityTextAreaRole, nil);
+}
+
+/* ---- Text content methods for VoiceOver ---- */
+
+- (id)accessibilityValue
+{
+  /* Return visible buffer text (capped at 10000 chars for safety).
+     VoiceOver reads this when navigating to the text area and after
+     ValueChangedNotification.  */
+  if (!emacsframe)
+    return @"";
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf)
+    return @"";
+
+  ptrdiff_t start_byte = BUF_BEGV_BYTE (curbuf);
+  ptrdiff_t byte_range = BUF_ZV_BYTE (curbuf) - start_byte;
+  ptrdiff_t range = BUF_ZV (curbuf) - BUF_BEGV (curbuf);
+
+  /* Cap at 10000 characters to avoid performance issues with large
+     buffers.  Recompute byte_range from the capped char range to
+     avoid truncating multibyte sequences (UTF-8 chars can be up to
+     4 bytes, so byte_range != range for non-ASCII content).  */
+  if (range > 10000)
+    {
+      range = 10000;
+      ptrdiff_t end_byte = buf_charpos_to_bytepos (curbuf,
+						    BUF_BEGV (curbuf) + range);
+      byte_range = end_byte - start_byte;
+    }
+
+  Lisp_Object str;
+  if (! NILP (BVAR (curbuf, enable_multibyte_characters)))
+    str = make_uninit_multibyte_string (range, byte_range);
+  else
+    str = make_uninit_string (range);
+  memcpy (SDATA (str), BUF_BYTE_ADDRESS (curbuf, start_byte), byte_range);
+
+  return [NSString stringWithLispString:str];
+}
+
+- (NSInteger)accessibilityNumberOfCharacters
+{
+  if (!emacsframe)
+    return 0;
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf)
+    return 0;
+
+  ptrdiff_t range = BUF_ZV (curbuf) - BUF_BEGV (curbuf);
+  return (NSInteger) MIN (range, 10000);
+}
+
+- (NSString *)accessibilitySelectedText
+{
+  /* Return text of the active region (Emacs selection).  Empty string
+     if no mark is active.  */
+  if (!emacsframe)
+    return @"";
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf || NILP (BVAR (curbuf, mark_active)))
+    return @"";
+
+  Lisp_Object str = ns_get_local_selection (QPRIMARY, QUTF8_STRING);
+  if (CONSP (str) && SYMBOLP (XCAR (str)))
+    {
+      str = XCDR (str);
+      if (CONSP (str) && NILP (XCDR (str)))
+	str = XCAR (str);
+    }
+  if (STRINGP (str))
+    return [NSString stringWithLispString:str];
+
+  return @"";
+}
+
+- (NSRange)accessibilitySelectedTextRange
+{
+  /* Return cursor position as a zero-length range.  VoiceOver uses
+     this with accessibilityBoundsForRange: to locate the caret.  */
+  if (!emacsframe)
+    return NSMakeRange (0, 0);
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf)
+    return NSMakeRange (0, 0);
+
+  ptrdiff_t pt = BUF_PT (curbuf) - BUF_BEGV (curbuf);
+  return NSMakeRange ((NSUInteger) pt, 0);
+}
+
+- (NSInteger)accessibilityInsertionPointLineNumber
+{
+  /* Return the VISUAL (screen) line number at point.  VoiceOver uses
+     this to detect line changes: if the number differs from last query,
+     it reads the full line; if same, it reads just one character.
+     We must count display lines (respecting wrapping, continuation,
+     window width) — not logical buffer lines delimited by newlines.
+     This matches iTerm2, which returns the screen row coordinate.  */
+  if (!emacsframe)
+    return 0;
+
+  struct window *w = XWINDOW (emacsframe->selected_window);
+  if (!w)
+    return 0;
+
+  struct buffer *b = XBUFFER (w->contents);
+  if (!b)
+    return 0;
+
+  struct buffer *old = current_buffer;
+  set_buffer_internal_1 (b);
+
+  /* Pass width = -1 so compute_motion determines the effective window
+     width exactly as vmotion does (consistent with accessibilityRangeForLine:
+     which uses vmotion).  On GUI frames with fringes, this uses the full
+     window_body_width; on TTY frames, it subtracts 1 for continuation marks.  */
+  struct position *pos = compute_motion (
+    BUF_BEGV (b), BUF_BEGV_BYTE (b),
+    0, 0, 0,			/* fromvpos, fromhpos, did_motion */
+    BUF_PT (b),			/* to */
+    MOST_POSITIVE_FIXNUM,	/* tovpos — large enough to not stop early */
+    0,				/* tohpos */
+    -1,				/* width — let compute_motion use window width */
+    w->hscroll, 0, w);
+
+  set_buffer_internal_1 (old);
+  return (NSInteger) pos->vpos;
+}
+
+- (NSRange)accessibilityVisibleCharacterRange
+{
+  /* Return range of characters visible in the current window.
+     Simplified to 0..min(bufsize,10000) matching accessibilityValue.  */
+  if (!emacsframe)
+    return NSMakeRange (0, 0);
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf)
+    return NSMakeRange (0, 0);
+
+  ptrdiff_t range = BUF_ZV (curbuf) - BUF_BEGV (curbuf);
+  return NSMakeRange (0, (NSUInteger) MIN (range, 10000));
+}
+
+- (NSString *)accessibilityStringForRange:(NSRange)nsrange
+{
+  /* Return buffer text for the given character range.  VoiceOver calls
+     this during character/word/line reading (VO+arrow keys).  */
+  if (!emacsframe)
+    return @"";
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf)
+    return @"";
+
+  ptrdiff_t start = BUF_BEGV (curbuf) + (ptrdiff_t) nsrange.location;
+  ptrdiff_t end = start + (ptrdiff_t) nsrange.length;
+  ptrdiff_t buf_end = BUF_ZV (curbuf);
+
+  if (start < BUF_BEGV (curbuf)) start = BUF_BEGV (curbuf);
+  if (end > buf_end) end = buf_end;
+  if (start >= end) return @"";
+
+  ptrdiff_t start_byte = buf_charpos_to_bytepos (curbuf, start);
+  ptrdiff_t end_byte = buf_charpos_to_bytepos (curbuf, end);
+  ptrdiff_t range = end - start;
+  ptrdiff_t byte_range = end_byte - start_byte;
+
+  Lisp_Object str;
+  if (! NILP (BVAR (curbuf, enable_multibyte_characters)))
+    str = make_uninit_multibyte_string (range, byte_range);
+  else
+    str = make_uninit_string (range);
+  memcpy (SDATA (str), BUF_BYTE_ADDRESS (curbuf, start_byte), byte_range);
+
+  return [NSString stringWithLispString:str];
+}
+
+- (NSAttributedString *)accessibilityAttributedStringForRange:(NSRange)nsrange
+{
+  /* Return attributed string for the range.  VoiceOver requires this
+     for text navigation.  We return a plain (unstyled) attributed
+     string — sufficient for screen reader use.  */
+  NSString *str = [self accessibilityStringForRange:nsrange];
+  return [[NSAttributedString alloc] initWithString:str];
+}
+
+- (NSInteger)accessibilityLineForIndex:(NSInteger)index
+{
+  /* Convert character index to VISUAL line number.  Must be consistent
+     with accessibilityInsertionPointLineNumber (both use visual lines
+     via compute_motion).  */
+  if (!emacsframe)
+    return 0;
+
+  struct window *w = XWINDOW (emacsframe->selected_window);
+  if (!w)
+    return 0;
+
+  struct buffer *b = XBUFFER (w->contents);
+  if (!b)
+    return 0;
+
+  ptrdiff_t charpos = BUF_BEGV (b) + (ptrdiff_t) index;
+  if (charpos > BUF_ZV (b))
+    charpos = BUF_ZV (b);
+  if (charpos < BUF_BEGV (b))
+    charpos = BUF_BEGV (b);
+
+  struct buffer *old = current_buffer;
+  set_buffer_internal_1 (b);
+
+  /* Pass width = -1 for consistency with vmotion (used by
+     accessibilityRangeForLine:).  See comment in
+     accessibilityInsertionPointLineNumber.  */
+  struct position *pos = compute_motion (
+    BUF_BEGV (b), BUF_BEGV_BYTE (b),
+    0, 0, 0,
+    charpos,
+    MOST_POSITIVE_FIXNUM, 0,
+    -1, w->hscroll, 0, w);
+
+  set_buffer_internal_1 (old);
+  return (NSInteger) pos->vpos;
+}
+
+- (NSRange)accessibilityRangeForLine:(NSInteger)line
+{
+  /* Return the character range for VISUAL line N.  VoiceOver uses
+     this to read an entire line when navigating by line.  Must be
+     consistent with accessibilityLineForIndex: (both use visual lines).
+     We use vmotion to find the start of visual line N, then advance
+     one more visual line to find the end.  Trailing newlines are
+     excluded from the range.  */
+  if (!emacsframe)
+    return NSMakeRange (0, 0);
+
+  struct window *w = XWINDOW (emacsframe->selected_window);
+  if (!w)
+    return NSMakeRange (0, 0);
+
+  struct buffer *b = XBUFFER (w->contents);
+  if (!b)
+    return NSMakeRange (0, 0);
+
+  ptrdiff_t begv = BUF_BEGV (b);
+  ptrdiff_t zv = BUF_ZV (b);
+
+  struct buffer *old = current_buffer;
+  set_buffer_internal_1 (b);
+
+  /* Move N visual lines from BEGV to reach the start of line N.  */
+  struct position *start_pos = vmotion (begv, BUF_BEGV_BYTE (b),
+					(EMACS_INT) line, w);
+  ptrdiff_t line_start = start_pos->bufpos;
+
+  /* Move 1 more visual line to find where this line ends.  */
+  ptrdiff_t start_byte = buf_charpos_to_bytepos (b, line_start);
+  struct position *end_pos = vmotion (line_start, start_byte, 1, w);
+  ptrdiff_t line_end = end_pos->bufpos;
+
+  /* If vmotion didn't move (last line in buffer), extend to ZV.  */
+  if (line_end <= line_start)
+    line_end = zv;
+
+  /* Exclude trailing newline — VoiceOver doesn't need it and would
+     announce "new line" at the end of each spoken line.  */
+  if (line_end > line_start)
+    {
+      ptrdiff_t last_byte = buf_charpos_to_bytepos (b, line_end - 1);
+      if (*BUF_BYTE_ADDRESS (b, last_byte) == '\n')
+	line_end--;
+    }
+
+  set_buffer_internal_1 (old);
+
+  ptrdiff_t start_idx = line_start - begv;
+  ptrdiff_t end_idx = line_end - begv;
+  if (start_idx < 0) start_idx = 0;
+  if (end_idx < start_idx) end_idx = start_idx;
+
+  return NSMakeRange ((NSUInteger) start_idx,
+		      (NSUInteger) (end_idx - start_idx));
+}
+
+- (NSRect)accessibilityFrameForRange:(NSRange)range
+{
+  /* Return screen rect for a character range.  This is the modern
+     NSAccessibilityProtocol equivalent of accessibilityBoundsForRange:.
+     We delegate to the same implementation.  */
+  return [self accessibilityBoundsForRange:range];
+}
+
+- (NSRange)accessibilityRangeForPosition:(NSPoint)point
+{
+  /* Return character range at a screen point.  VoiceOver uses this
+     for mouse-based exploration.  Stub: returns empty range at 0.
+     A full implementation would need hit-testing against the glyph
+     matrix, which Emacs doesn't expose to AppKit.  */
+  (void) point;
+  return NSMakeRange (0, 0);
+}
+
+- (NSRange)accessibilityRangeForIndex:(NSInteger)index
+{
+  /* Return the range of the character at the given index.  VoiceOver
+     uses this for character-by-character navigation.  */
+  if (!emacsframe)
+    return NSMakeRange (0, 0);
+
+  struct buffer *curbuf
+    = XBUFFER (XWINDOW (emacsframe->selected_window)->contents);
+  if (!curbuf)
+    return NSMakeRange (0, 0);
+
+  ptrdiff_t range = BUF_ZV (curbuf) - BUF_BEGV (curbuf);
+  ptrdiff_t maxrange = MIN (range, 10000);
+
+  if (index < 0 || index >= maxrange)
+    return NSMakeRange (0, 0);
+
+  return NSMakeRange ((NSUInteger) index, 1);
+}
+
+- (NSArray *)accessibilitySelectedTextRanges
+{
+  /* Return array of selected ranges.  VoiceOver may query this
+     (plural) form instead of the singular selectedTextRange.  */
+  NSRange r = [self accessibilitySelectedTextRange];
+  return @[[NSValue valueWithRange:r]];
+}
+
+- (BOOL)isAccessibilityFocused
+{
+  /* Always report focused — matches iTerm2 behavior.  */
+  return YES;
+}
+
+- (NSString *)accessibilityLabel
+{
+  /* Provide an identifying label for VoiceOver.  Include the current
+     buffer name so VoiceOver announces it on window/frame switch
+     (triggered by FocusedUIElementChangedNotification).  */
+  if (!emacsframe)
+    return @"Emacs";
+
+  struct window *w = XWINDOW (emacsframe->selected_window);
+  if (!w)
+    return @"Emacs";
+
+  struct buffer *b = XBUFFER (w->contents);
+  if (!b)
+    return @"Emacs";
+
+  Lisp_Object name = BVAR (b, name);
+  if (STRINGP (name))
+    return [NSString stringWithFormat:@"Emacs — %@",
+			[NSString stringWithLispString:name]];
+
+  return @"Emacs";
+}
+
+/* ---- Cursor position for Zoom (via accessibilityBoundsForRange:) ----
+
+   accessibilityFrame intentionally returns the VIEW's frame (standard
+   behavior) so VoiceOver draws its focus ring around the text area.
+   The cursor location is exposed through accessibilityBoundsForRange:
+   which AT tools query using the selectedTextRange.  */
+
+- (NSRect)accessibilityFrame
+{
+  /* View's screen frame — standard NSView behavior.  Do NOT return
+     the cursor rect here; that causes a duplicate cursor overlay.  */
+  return [super accessibilityFrame];
+}
+
+- (NSRect)accessibilityBoundsForRange:(NSRange)range
+{
+  /* Return cursor screen rect.  AT tools call this with the
+     selectedTextRange to locate the insertion point.  We return the
+     cursor position regardless of requested range because Emacs does
+     not expose character-level geometry to AppKit.  */
+  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];
+}
+
+/* ---- Legacy attribute APIs (pre-10.10 compatibility) ---- */
+
+- (NSArray *)accessibilityAttributeNames
+{
+  NSArray *superAttrs = [super accessibilityAttributeNames];
+  if (superAttrs == nil)
+    superAttrs = @[];
+  return [superAttrs arrayByAddingObjectsFromArray:
+	    @[NSAccessibilityRoleAttribute,
+	      NSAccessibilityValueAttribute,
+	      NSAccessibilitySelectedTextAttribute,
+	      NSAccessibilitySelectedTextRangeAttribute,
+	      NSAccessibilityNumberOfCharactersAttribute,
+	      NSAccessibilityVisibleCharacterRangeAttribute,
+	      NSAccessibilityInsertionPointLineNumberAttribute]];
+}
+
+- (id)accessibilityAttributeValue:(NSString *)attribute
+{
+  if ([attribute isEqualToString:NSAccessibilityRoleAttribute])
+    return NSAccessibilityTextAreaRole;
+
+  if ([attribute isEqualToString:NSAccessibilityValueAttribute])
+    return [self accessibilityValue];
+
+  if ([attribute isEqualToString:NSAccessibilitySelectedTextAttribute])
+    return [self accessibilitySelectedText];
+
+  if ([attribute isEqualToString:NSAccessibilitySelectedTextRangeAttribute])
+    return [NSValue valueWithRange:[self accessibilitySelectedTextRange]];
+
+  if ([attribute isEqualToString:NSAccessibilityNumberOfCharactersAttribute])
+    return @([self accessibilityNumberOfCharacters]);
+
+  if ([attribute isEqualToString:NSAccessibilityVisibleCharacterRangeAttribute])
+    return [NSValue valueWithRange:[self accessibilityVisibleCharacterRange]];
+
+  if ([attribute isEqualToString:NSAccessibilityInsertionPointLineNumberAttribute])
+    return @([self accessibilityInsertionPointLineNumber]);
+
+  return [super accessibilityAttributeValue:attribute];
+}
+
+- (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 */