From 403a1c4664e7491c20eac86c143898bc366a57bc Mon Sep 17 00:00:00 2001 From: Martin Sukany Date: Sat, 28 Feb 2026 14:46:25 +0100 Subject: [PATCH] ns: announce overlay completion candidates for VoiceOver Completion frameworks such as Vertico, Ivy, and Icomplete render candidates via overlay before-string/after-string properties rather than buffer text. Without this patch, VoiceOver cannot read overlay-based completion UIs. Identify the selected candidate by scanning overlay strings for a face whose symbol name contains "current" or "selected" --- this matches vertico-current, icomplete-selected-match, ivy-current-match and similar framework faces without hard-coding any specific name. Key implementation details: - The overlay detection branch runs independently (if, not else-if) of the text-change branch, because Vertico bumps both BUF_MODIFF (via text property changes in vertico--prompt-selection) and BUF_OVERLAY_MODIFF (via overlay-put) in the same command cycle. - Use BUF_CHARS_MODIFF to gate ValueChanged notifications, since text property changes bump BUF_MODIFF but not BUF_CHARS_MODIFF. - Remove BUF_OVERLAY_MODIFF from ensureTextCache validity checks to prevent a race condition where VoiceOver AX queries silently consume the overlay change before the notification dispatch runs. - Announce via AnnouncementRequested to NSApp with High priority. Do not post SelectedTextChanged (that reads the AX text at cursor position, which is the minibuffer input, not the candidate). - Zoom tracking: store the selected candidate's glyph row rect in overlayZoomRect. draw_window_cursor checks overlayZoomActive and uses the stored rect instead of the text cursor rect, keeping Zoom focused on the candidate. The flag is cleared when the user types (BUF_CHARS_MODIFF changes) to return Zoom to the cursor. * src/nsterm.h (EmacsView): Add overlayZoomActive, overlayZoomRect. (EmacsAccessibilityBuffer): Add cachedCharsModiff. * src/nsterm.m (ns_ax_face_is_selected): New predicate. (ns_ax_selected_overlay_text): New function. (ns_draw_window_cursor): Use overlayZoomRect when active. (EmacsAccessibilityBuffer ensureTextCache): Remove overlay_modiff. (EmacsAccessibilityBuffer postAccessibilityNotificationsForFrame:): Independent overlay branch, BUF_CHARS_MODIFF gating, candidate announcement with overlay Zoom rect storage. --- src/nsterm.h | 3 + src/nsterm.m | 252 ++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 244 insertions(+), 11 deletions(-) diff --git a/src/nsterm.h b/src/nsterm.h index 51c30ca..5c15639 100644 --- a/src/nsterm.h +++ b/src/nsterm.h @@ -507,6 +507,7 @@ typedef struct ns_ax_visible_run @property (nonatomic, assign) ptrdiff_t cachedOverlayModiff; @property (nonatomic, assign) ptrdiff_t cachedTextStart; @property (nonatomic, assign) ptrdiff_t cachedModiff; +@property (nonatomic, assign) ptrdiff_t cachedCharsModiff; @property (nonatomic, assign) ptrdiff_t cachedPoint; @property (nonatomic, assign) BOOL cachedMarkActive; @property (nonatomic, copy) NSString *cachedCompletionAnnouncement; @@ -591,6 +592,8 @@ typedef NS_ENUM (NSInteger, EmacsAXSpanType) BOOL accessibilityUpdating; @public /* Accessed by ns_draw_phys_cursor (C function). */ NSRect lastAccessibilityCursorRect; + BOOL overlayZoomActive; + NSRect overlayZoomRect; #endif BOOL font_panel_active; NSFont *font_panel_result; diff --git a/src/nsterm.m b/src/nsterm.m index 1780194..5c3758a 100644 --- a/src/nsterm.m +++ b/src/nsterm.m @@ -3258,7 +3258,12 @@ ns_draw_window_cursor (struct window *w, struct glyph_row *glyph_row, && MAC_OS_X_VERSION_MIN_REQUIRED >= 101000 if (UAZoomEnabled ()) { - NSRect windowRect = [view convertRect:r toView:nil]; + /* When overlay completion is active (e.g. Vertico), + focus Zoom on the selected candidate row instead + of the text cursor. */ + NSRect zoomSrc = view->overlayZoomActive + ? view->overlayZoomRect : r; + NSRect windowRect = [view convertRect:zoomSrc toView:nil]; NSRect screenRect = [[view window] convertRectToScreen:windowRect]; CGRect cgRect = NSRectToCGRect (screenRect); @@ -6915,11 +6920,145 @@ ns_create_font_panel_buttons (id target, SEL select, SEL cancel_action) are truncated for accessibility purposes. */ #define NS_AX_TEXT_CAP 100000 +/* Return true if FACE is or contains a face symbol whose name + includes "current" or "selected", indicating a highlighted + completion candidate. Works for vertico-current, + icomplete-selected-match, ivy-current-match, etc. */ +static bool +ns_ax_face_is_selected (Lisp_Object face) +{ + if (SYMBOLP (face) && !NILP (face)) + { + const char *name = SSDATA (SYMBOL_NAME (face)); + if (strstr (name, "current") || strstr (name, "selected")) + return true; + } + if (CONSP (face)) + { + for (Lisp_Object tail = face; CONSP (tail); tail = XCDR (tail)) + if (ns_ax_face_is_selected (XCAR (tail))) + return true; + } + return false; +} + +/* Extract the currently selected candidate text from overlay display + strings. Completion frameworks render candidates as overlay + before-string/after-string and highlight the current candidate + with a face whose name contains "current" or "selected" + (e.g. vertico-current, icomplete-selected-match, ivy-current-match). + + Scan all overlays in the buffer region [BEG, END), find the line + whose face matches the selection heuristic, and return it (already + trimmed of surrounding whitespace). + + Also set *OUT_LINE_INDEX to the 0-based visual line index of the + selected candidate (for Zoom positioning), counting only non-trivial + lines. Set to -1 if not found. + + Returns nil if no selected candidate is found. */ +static NSString * +ns_ax_selected_overlay_text (struct buffer *b, + ptrdiff_t beg, ptrdiff_t end, + int *out_line_index) +{ + *out_line_index = -1; + + Lisp_Object ov_list = Foverlays_in (make_fixnum (beg), + make_fixnum (end)); + + for (Lisp_Object tail = ov_list; CONSP (tail); tail = XCDR (tail)) + { + Lisp_Object ov = XCAR (tail); + Lisp_Object strings[2]; + strings[0] = Foverlay_get (ov, intern_c_string ("before-string")); + strings[1] = Foverlay_get (ov, intern_c_string ("after-string")); + + for (int s = 0; s < 2; s++) + { + if (!STRINGP (strings[s])) + continue; + + Lisp_Object str = strings[s]; + ptrdiff_t slen = SCHARS (str); + if (slen == 0) + continue; + + /* Scan for newline positions using SDATA for efficiency. */ + const unsigned char *data = SDATA (str); + ptrdiff_t byte_len = SBYTES (str); + ptrdiff_t line_starts[512]; + ptrdiff_t line_ends[512]; + int nlines = 0; + ptrdiff_t char_pos = 0, byte_pos = 0, lstart = 0; + + while (byte_pos < byte_len && nlines < 512) + { + if (data[byte_pos] == '\n') + { + if (char_pos > lstart) + { + line_starts[nlines] = lstart; + line_ends[nlines] = char_pos; + nlines++; + } + lstart = char_pos + 1; + } + if (STRING_MULTIBYTE (str)) + byte_pos += BYTES_BY_CHAR_HEAD (data[byte_pos]); + else + byte_pos++; + char_pos++; + } + if (char_pos > lstart && nlines < 512) + { + line_starts[nlines] = lstart; + line_ends[nlines] = char_pos; + nlines++; + } + + /* Find the line whose face indicates selection. Track + visual line index for Zoom (skip whitespace-only lines + like Vertico's leading cursor-space). */ + int candidate_idx = 0; + for (int li = 0; li < nlines; li++) + { + Lisp_Object face + = Fget_text_property (make_fixnum (line_starts[li]), + Qface, str); + if (ns_ax_face_is_selected (face)) + { + Lisp_Object line + = Fsubstring_no_properties ( + str, + make_fixnum (line_starts[li]), + make_fixnum (line_ends[li])); + NSString *text = [NSString stringWithLispString:line]; + text = [text stringByTrimmingCharactersInSet: + [NSCharacterSet + whitespaceAndNewlineCharacterSet]]; + if ([text length] > 0) + { + *out_line_index = candidate_idx; + return text; + } + } + + /* Count non-trivial lines as candidates for Zoom. */ + if (line_ends[li] - line_starts[li] > 1) + candidate_idx++; + } + } + } + + return nil; +} + + /* Build accessibility text for window W, skipping invisible text. Populates *OUT_START with the buffer start charpos. Populates *OUT_RUNS with an array of visible runs and *OUT_NRUNS with the count. Caller must free *OUT_RUNS with xfree(). */ - static NSString * ns_ax_buffer_text (struct window *w, ptrdiff_t *out_start, ns_ax_visible_run **out_runs, NSUInteger *out_nruns) @@ -7556,6 +7695,7 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem, @synthesize cachedOverlayModiff; @synthesize cachedTextStart; @synthesize cachedModiff; +@synthesize cachedCharsModiff; @synthesize cachedPoint; @synthesize cachedMarkActive; @synthesize cachedCompletionAnnouncement; @@ -7609,16 +7749,15 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem, return; ptrdiff_t modiff = BUF_MODIFF (b); - ptrdiff_t overlay_modiff = BUF_OVERLAY_MODIFF (b); ptrdiff_t pt = BUF_PT (b); NSUInteger textLen = cachedText ? [cachedText length] : 0; - /* Track both BUF_MODIFF and BUF_OVERLAY_MODIFF. Overlay-only - changes (e.g., timer-based completion highlight move without - text edit) bump overlay_modiff but not modiff. Also detect - narrowing/widening which changes BUF_BEGV without bumping - either modiff counter. */ + /* Cache validity: track BUF_MODIFF and buffer narrowing. + Do NOT track BUF_OVERLAY_MODIFF here --- overlay text is not + included in the cached AX text (it is handled separately via + explicit announcements). Including overlay_modiff would + silently update cachedOverlayModiff and prevent the + notification dispatch from detecting overlay changes. */ if (cachedText && cachedTextModiff == modiff - && cachedOverlayModiff == overlay_modiff && cachedTextStart == BUF_BEGV (b) && pt >= cachedTextStart && (textLen == 0 @@ -7635,7 +7774,6 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem, [cachedText release]; cachedText = [text retain]; cachedTextModiff = modiff; - cachedOverlayModiff = overlay_modiff; cachedTextStart = start; if (visibleRuns) @@ -8789,10 +8927,102 @@ ns_ax_completion_text_for_span (EmacsAccessibilityBuffer *elem, BOOL markActive = !NILP (BVAR (b, mark_active)); /* --- Text changed (edit) --- */ + ptrdiff_t chars_modiff = BUF_CHARS_MODIFF (b); if (modiff != self.cachedModiff) { self.cachedModiff = modiff; - [self postTextChangedNotification:point]; + /* Only post ValueChanged when actual characters changed. + Text property changes (e.g. face updates from + vertico--prompt-selection) bump BUF_MODIFF but not + BUF_CHARS_MODIFF. Posting ValueChanged for property-only + changes causes VoiceOver to say "new line" when the diff + is non-empty due to overlay content changes. */ + if (chars_modiff != self.cachedCharsModiff) + { + self.cachedCharsModiff = chars_modiff; + self.emacsView->overlayZoomActive = NO; + [self postTextChangedNotification:point]; + } + } + + + /* --- Overlay content changed (e.g. Vertico/Ivy candidate switch) --- + Check independently of the modiff branch above, because + frameworks like Vertico bump BOTH BUF_MODIFF (via text property + changes in vertico--prompt-selection) and BUF_OVERLAY_MODIFF + (via overlay-put) in the same command cycle. If this were an + else-if, the modiff branch would always win and overlay + announcements would never fire. + Do NOT invalidate the text cache --- the buffer text has not + changed, and cache invalidation causes VoiceOver to diff old + vs new AX text and announce spurious "new line". */ + if (BUF_OVERLAY_MODIFF (b) != self.cachedOverlayModiff) + { + self.cachedOverlayModiff = BUF_OVERLAY_MODIFF (b); + + int selected_line = -1; + NSString *candidate + = ns_ax_selected_overlay_text (b, BUF_BEGV (b), BUF_ZV (b), + &selected_line); + if (candidate) + { + /* Deduplicate: only announce when the candidate changed. */ + if (![candidate isEqualToString: + self.cachedCompletionAnnouncement]) + { + self.cachedCompletionAnnouncement = candidate; + + /* Announce the candidate text directly via NSApp. + Do NOT post SelectedTextChanged --- that would cause + VoiceOver to read the AX text at the cursor position + (the minibuffer input line), not the overlay candidate. + AnnouncementRequested with High priority interrupts + any current speech and announces our text. */ + NSDictionary *annInfo = @{ + NSAccessibilityAnnouncementKey: candidate, + NSAccessibilityPriorityKey: + @(NSAccessibilityPriorityHigh) + }; + ns_ax_post_notification_with_info ( + NSApp, + NSAccessibilityAnnouncementRequestedNotification, + annInfo); + + /* --- Zoom tracking for overlay candidates --- + Store the candidate row rect so draw_window_cursor + focuses Zoom there instead of on the text cursor. + Cleared when the user types (chars_modiff change). */ + if (selected_line >= 0) + { + struct window *w2 = [self validWindow]; + if (w2 && w2->current_matrix) + { + EmacsView *view = self.emacsView; + int target_vrow = selected_line + 1; + int nrows = w2->current_matrix->nrows; + if (target_vrow < nrows) + { + struct glyph_row *row + = w2->current_matrix->rows + target_vrow; + if (row->enabled_p + && row->visible_height > 0) + { + view->overlayZoomRect = NSMakeRect ( + w2->pixel_left, + WINDOW_TOP_EDGE_Y (w2) + row->y, + w2->pixel_width, + row->visible_height); + view->overlayZoomActive = YES; + } + } + } + } + } + } + else + { + self.emacsView->overlayZoomActive = NO; + } } /* --- Cursor moved or selection changed --- -- 2.43.0