The review is written to `/tmp/emacs-doom-review/REVIEW-FINAL.md` (418 lines). Here's the summary of findings: --- ## Review Summary **Overall verdict: READY WITH MINOR FIXES** The series has matured well through six rounds. Architecture is sound, threading model is correct, performance claims are supportable. Two items block upstream submission: ### Must fix **Patch 0002** — Contains an unrelated functional change: the window-resize title string changes `strstr(t, " — ")` and `esprintf(..., "%s — ...")` from Unicode em-dash to triple-dash `---`. This is a behavioral change to non-accessibility code embedded in an accessibility patch. A maintainer will catch it immediately. **Patch 0007** — The commit message claims to introduce `ns_ax_face_is_selected` as a new function, but no such function appears in the diff. The actual code calls `ns_face_name_matches_selected_p` from patch 0000. The ChangeLog entry must be corrected. ### Structural (must fix before submission) **[PATCH 1/9] numbering** — All nine patches are numbered as one series, but the README says 0000 is independent of 0001–0008. For emacs-devel submission, either add a `[PATCH 0/9]` cover letter explaining the split, or submit 0000 separately as `[PATCH 1/1]`. ### Notable nits (fix recommended) - `goto skip_overlay_scan` in patch 0007 — unusual in Emacs C; Stefan Monnier will likely ask for a nested `if` instead - "Known Limitations" fifth bullet in patch 0006 ("Block-style cursors are handled correctly...") is a feature, not a limitation - "AT" abbreviation in commit messages — spell out "assistive technology" - Patch 0006 commit message references an `@xref` that isn't there ### What's clean (no action needed) Patches 0003, 0004, 0005 are LGTM. The threading model (AX thread → dispatch_sync to main), the `@synchronized` cache guards, `block_input`/`unblock_input` specpdl protection, GNUstep exclusion, and performance claims all check out. p` TTL caching with `CFAbsoluteTimeGetCurrent()` is well motivated; the 1-second TTL justification is documented clearly. - `ns_face_name_matches_selected_p` using `strstr` on face symbol names is an accepted heuristic; the comment acknowledges it. - specpdl unwind protection is correct throughout. - `ns_zoom_find_child_frame_candidate`: inside the FOR_EACH_FRAME body, `block_input()` is called before `SPECPDL_INDEX()`. In practice this is safe (SPECPDL_INDEX cannot fail), but the canonical Emacs ordering is SPECPDL_INDEX -> record_unwind -> block_input. Patch 0008 later reverses this order in `ns_ax_buffer_text` with an explanatory comment; 0000 is left inconsistent. Nit only. - Double blank line before `#ifdef NS_IMPL_COCOA` at the top of the new block (~line 93 of the diff). GNU Emacs style uses a single blank line between top-level definitions. - Block scope `{ EmacsView *view = ...; }` in `ns_draw_window_cursor` is unnecessary (no outer `view` in scope at that point); the extra braces can be removed. **Verdict: LGTM with nits** -- fix numbering before submission; the code is otherwise clean. --- ### 0001: Add accessibility base classes and helpers [PATCH 2/9] **Subject / commit message** Correct format. The commit message abbreviates "AT" for "assistive technology" -- spell it out for an emacs-devel audience. **Code quality** - GC safety analysis on `lispWindow` is thorough and correct. - `@synchronized (self)` guards on visibleRuns/lineStartOffsets are correct; they protect against concurrent reads from the AX server thread while the main thread rebuilds the cache. - `ns_ax_buffer_text` correctly uses `Fbuffer_substring_no_properties` instead of raw `BUF_BYTE_ADDRESS` to handle the buffer gap. ✓ - `Fget_char_property (pos, Qinvisible, Qnil)` with Qnil meaning the current buffer is correct after `set_buffer_internal_1(b)`. ✓ - `TEXT_PROP_MEANS_INVISIBLE` correctly mirrors xdisp.c logic. ✓ - The stub `@implementation EmacsAccessibilityBuffer (InteractiveSpans)` has a comment reading "full implementation added in patch 0004". Once the series numbering is resolved this should say "in the following patch" or match the final [PATCH N/M] numbers. **Verdict: LGTM with nits.** --- ### 0002: Implement buffer accessibility element [PATCH 3/9] **SERIOUS ISSUE -- unrelated functional change** Deep in the diff, in the context of `windowWillResize:toSize:`, the patch changes: ```diff - char *pos = strstr (t, " \xe2\x80\x94 "); + char *pos = strstr (t, " --- "); ... - esprintf (size_title, "%s \xe2\x80\x94 (%d x %d)", old_title, cols, rows); + esprintf (size_title, "%s --- (%d x %d)", old_title, cols, rows); ``` This replaces a Unicode em-dash (U+2014) with three ASCII hyphens in the *functional* window-resize title string. This: - Is unrelated to accessibility. - Changes the visual appearance of the resize title bar. - Must be in its own commit (with its own ChangeLog entry and justification) or reverted. A maintainer will reject the patch if they spot this. All other content in this patch is correct: - `@synchronized (self)` in `invalidateTextCache` correctly releases Objective-C objects under the lock; `invalidateInteractiveSpans` is called outside the lock to avoid mutex inversion. ✓ - Binary search in `accessibilityIndexForCharpos:` and `charposForAccessibilityIndex:` is correct; the O(1) ASCII fast-path is well-motivated and the comment explains why it matters. ✓ - `setAccessibilitySelectedTextRange:` correctly deactivates the mark (with explanatory comment about VoiceOver word-boundary hints). ✓ - `dispatch_async` for setters (no return value needed) vs. `dispatch_sync` for getters (return value required) is the correct pattern throughout. ✓ - `accessibilityStyleRangeForIndex:` is the only getter without its own main-thread check; it relies on two sub-calls that each dispatch individually. Correct but two round-trips instead of one. Minor nit. **Verdict: Needs work** -- remove the window title em-dash change. --- ### 0003: Add AX notifications and mode-line element [PATCH 4/9] **Subject / commit message** Correct. ChangeLog entries are detailed and accurate. **Code quality** - `postTextChangedNotification:` single-character fast path (grab the inserted char for `AXTextChangeValue`) is a useful optimization. - `postFocusedCursorNotification:direction:granularity:markActive: oldMarkActive:` granularity reasoning -- omit for char moves to prevent block-cursor double-speech -- matches documented WebKit behaviour. ✓ - `postCompletionAnnouncementForBuffer:point:` four-level fallback chain (completion--string -> mouse-face -> completions-highlight overlay -> line text) is comprehensive. - `[ws mutableCopy]` / `[trims release]` in the word-announcement path is correct MRC. ✓ - `EmacsAccessibilityModeLine` returns `NSAccessibilityStaticTextRole`; `accessibilityValue` delegates to `ns_ax_mode_line_text`. Correct. **Verdict: LGTM.** --- ### 0004: Add interactive span elements for Tab [PATCH 5/9] **Subject / commit message** Correct. **Code quality** - `ns_ax_scan_interactive_spans` priority ordering (widget > button > follow-link > org-link > completion > keymap-overlay) is a reasonable policy; documented in the function comment. - Skip-to-next-change logic uses the minimum of per-property change points: O(properties * log(buffer)) rather than O(chars). ✓ - `EmacsAccessibilityInteractiveSpan.isAccessibilityFocused` reads `pb.cachedPoint` (a plain `ptrdiff_t`) without `@synchronized`. This is safe because `cachedPoint` is only written on the main thread and the ivar is machine-word aligned (naturally atomic on ARM64/x86-64). Acceptable; a brief comment noting this would be welcome. - `setAccessibilityFocused:` correctly uses `dispatch_async` with the Lisp_Object-captured-by-value comment. ✓ - Removes the stub `@implementation` from patch 0001 cleanly. ✓ **Verdict: LGTM.** --- ### 0005: Wire accessibility into EmacsView and redisplay [PATCH 6/9] **Subject / commit message** Correct. **Code quality** - Re-entrance guard (`accessibilityUpdating`) is placed correctly at the start of `postAccessibilityUpdates`. ✓ - `ns_update_accessibility_state` uses `AXIsProcessTrustedWithOptions` with `kAXTrustedCheckOptionPrompt: @NO` -- does not prompt the user. ✓ - `(__bridge id)` and `(__bridge CFDictionaryRef)` casts in MRC context are correct for toll-free bridging (no ownership transfer). ✓ - `com.apple.accessibility.api` distributed notification is the standard (if undocumented) mechanism used by WebKit et al. ✓ - Window-switch detection via `lastSelectedWindow` comparison is clean. - `accessibilityBoundsForRange:` / `accessibilityFrameForRange:` / the legacy `accessibilityAttributeValue:forParameter:` delegation chain is complete and handles both modern and pre-10.10 AX API callers. ✓ - `postAccessibilityUpdates` calls `rebuildAccessibilityTree` before the per-element notification loop when the tree is stale, with a clear comment explaining why (cannot diff state after fresh elements are created). ✓ **Verdict: LGTM.** --- ### 0006: doc: Add VoiceOver section to macOS appendix [PATCH 7/9] **Texinfo structure** - `@node VoiceOver Accessibility` inserted between `Mac / GNUstep Events` and `GNUstep Support`. Menu entry correctly added. ✓ - `@cindex`, `@vindex`, `@itemize @bullet`, `@subheading` all used correctly. ✓ - `@section` title "VoiceOver Accessibility (macOS)" is appropriate for the macOS appendix. **Content issue** In the "Known Limitations" `@itemize`, the fifth bullet reads: Block-style cursors are handled correctly: character navigation announces the character at the cursor position, not the character before it. This is not a limitation -- it is a correctness feature. It does not belong in a "Known Limitations" section. Remove this bullet or move it to the main feature description above. **Commit message note** The commit message says "Use @xref for cross-reference at sentence start" but no `@xref` appears in the added Texinfo. The note is stale from a previous revision; remove it or add the intended @xref. **Verdict: LGTM with nits** -- fix the Known Limitations bullet; clean up the @xref note in the commit message. --- ### 0007: Announce overlay completions to VoiceOver [PATCH 8/9] **SERIOUS ISSUE -- commit message describes non-existent function** The commit message states: * src/nsterm.m (ns_ax_face_is_selected): New static function; matches 'current', 'selected', 'selection' in face symbol names. No function named `ns_ax_face_is_selected` appears anywhere in this patch. The actual code calls `ns_face_name_matches_selected_p`, which was introduced in patch 0000. The commit message must be corrected to remove this spurious ChangeLog entry. A maintainer applying the patch would immediately notice the claimed function does not appear in the diff. **Code quality** - `ns_ax_selected_overlay_text` uses `SDATA` for the newline scan and correctly notes the data pointer is used only before Lisp calls that could trigger GC. ✓ - Stack-allocated `line_starts[512]` / `line_ends[512]` is safe given the vertico-count upper bound and the 512-line cap. ✓ - `BUF_CHARS_MODIFF` (not `BUF_MODIFF`) now gates `ValueChanged`; the reason (text-property-only changes from font-lock / Vertico prompt bump BUF_MODIFF but not BUF_CHARS_MODIFF) is well-explained. ✓ - Separate `if` for `BUF_OVERLAY_MODIFF` (not `else if`) correctly handles frameworks that bump both counters in one command cycle. ✓ - Removing `ensureTextCache` from the cursor-moved branch prevents the O(visible-buffer-text) rebuild cost on every keystroke. ✓ - `goto skip_overlay_scan` is unusual in Emacs C code. GNU Emacs does use goto for error exits, but using it to skip over a block is more readable as a nested `if (!MINI_WINDOW_P (w) && !didTextChange)`. Stefan Monnier is likely to request a refactor here. - `block_input` / `record_unwind_protect_void` ordering in `ns_ax_buffer_text` is corrected and documented. ✓ - Em-dash to `---` conversions in *comments* are cosmetic cleanup; acceptable (unlike the functional string changes in patch 0002). **Verdict: Needs work** -- fix the commit message; consider refactoring the goto. --- ### 0008: Announce child frame completions to VoiceOver [PATCH 9/9] **Subject / commit message** Correct and detailed. ChangeLog entries accurately describe all changes. **Code quality** - `voiceoverSetPoint` flag design (set in `setAccessibilitySelectedText Range:`, consumed and reset in the next notification cycle) is correct and clean. ✓ - `singleLineMove` adjacency detection (NSRange boundary comparison) is package-agnostic; no evil/doom/spacemacs-specific code. ✓ - `childFrameLastBuffer` stored as `BVAR(b, name)` (an interned symbol, always reachable from obarray) rather than a raw buffer pointer is the correct GC-safe approach. The comment explaining this is clear. ✓ - `childFrameLastCandidate` as a `char *` with `xstrdup`/`xfree` is correct C memory management; freed in `dealloc`. ✓ - `postEchoAreaAnnouncementIfNeeded` reads `echo_area_buffer[0]` directly with a comment explaining why `with_echo_area_buffer` is not used. The `minibuf_level == 0` guard is correct. ✓ - Re-entrance guard comment correctly notes `announceChildFrameCompletion` makes Lisp calls that can trigger redisplay; the guard is placed before the call. ✓ - `childFrameCompletionActive` + child-frame-still-visible check for restoring VoiceOver focus after popup close is clean. ✓ - `postFocusedCursorNotification:` updated to omit direction/granularity for discontiguous jumps (let VoiceOver determine what to read) matches the new reasoning about org-agenda blank-line gaps. ✓ - NEWS entry upgraded from `---` to `+++` now that documentation exists (added in patch 0006). ✓ - Minor: `announceChildFrameCompletion` has a spurious blank line between the opening `{` and the first comment. Cosmetic only. **Verdict: LGTM with nits.** --- ## Cross-Cutting Issues ### 1. Patch numbering inconsistency (structural -- must fix) All nine patch files carry [PATCH 1/9]-[PATCH 9/9], implying a single series. The README documents 0000 and 0001-0008 as *independent*. For upstream submission via git-send-email, either: - Treat all nine as one series with a [PATCH 0/9] cover letter; or - Separate 0000 into its own submission ([PATCH 1/1]) and renumber the VoiceOver series [PATCH 1/8]-[PATCH 8/8]. ### 2. Em-dash conversion in functional code (serious -- must fix in 0002) Em-dash to triple-dash conversions in *comments* (patches 0007, 0008) are acceptable style cleanup. The same conversion in *functional string literals* in patch 0002 (`strstr` / `esprintf` window title code) is a behavioral change that does not belong in an accessibility patch. ### 3. block_input ordering inconsistency (nit) Patches 0001-0006 use `SPECPDL_INDEX -> record_unwind -> block_input`. Patch 0008 (and a targeted fix in 0007) adopt `block_input -> record_unwind` and document why. Both orderings are safe in practice, but the series leaves them inconsistent across the added functions. ### 4. "AT" abbreviation in commit messages (nit) Patches 0001 and 0005 use "AT" for "assistive technology" in commit messages without expanding it. Spell it out on first use. ### 5. Stub comment reference to "patch 0004" (nit) The stub `@implementation EmacsAccessibilityBuffer (InteractiveSpans)` in patch 0001 says "full implementation added in patch 0004". Once the series numbering is finalised, update this to match the actual [PATCH N] number, or change it to "the following patch." ### 6. Threading model assessment The dispatch_sync-to-main pattern for all AX getter methods is correct and matches WebKit's approach. The dispatch_async-for-setters pattern is correct (no return value needed). The @synchronized blocks on the shared cache are correctly scoped. The re-entrance guard in `postAccessibilityUpdates` is correctly placed. No threading issues found. ### 7. GNUstep exclusion All new code is within `#ifdef NS_IMPL_COCOA` guards. GNUstep is correctly excluded. ✓ ### 8. Performance claims - O(log n) index lookups via binary search on visible runs: correct. ✓ - O(log L) line queries via precomputed lineStartOffsets: correct. ✓ - BUF_MODIFF gating (not BUF_CHARS_MODIFF) for cache validity: correct and thoroughly justified. ✓ - Zero overhead when `ns_accessibility_enabled` is nil: verified by TESTING.txt item 14. ✓ --- ## Verdict | Patch | Files | Status | |-------|-------|--------| | 0000 | nsterm.h, nsterm.m, NEWS | **LGTM with nits** -- fix numbering; minor style nits | | 0001 | nsterm.h, nsterm.m | **LGTM with nits** -- spell out "AT"; update stub comment | | 0002 | nsterm.m | **Needs work** -- remove em-dash/triple-dash change from window-resize string | | 0003 | nsterm.m | **LGTM** | | 0004 | nsterm.m | **LGTM** | | 0005 | nsterm.m, NEWS | **LGTM** | | 0006 | macos.texi, nsterm.m | **LGTM with nits** -- fix Known Limitations bullet; clarify @xref note | | 0007 | nsterm.h, nsterm.m | **Needs work** -- fix commit message (remove spurious ns_ax_face_is_selected entry); consider refactoring goto | | 0008 | nsterm.h, nsterm.m, macos.texi, NEWS | **LGTM with nits** -- remove spurious blank line in method body | **Bottom line**: Two patches need targeted fixes before submission (0002: remove unrelated string change; 0007: correct commit message). After those fixes, the series is ready for emacs-devel.