Emacs Core and OS Accessibility Bridge: Overlay Communication

Direct answer

Custom overlays in Emacs are not automatically mapped to OS accessibility objects, and core Emacs does not provide a stable Elisp API to register an arbitrary overlay in the platform accessibility tree or to force an immediate tree refresh. For rapid text mutation, group related edits and let the GUI toolkit coalesce change notifications rather than attempting per-character accessibility updates.

Confirmed facts versus likely explanation

Confirmed facts

• Emacs overlays created with make-overlay and annotated with overlay-put are Lisp display objects. Properties such as face or display control visual rendering only.
• OS accessibility coverage depends on the Emacs build: GTK/AT-SPI on Linux, Cocoa/AX on macOS, and W32 UI Automation/MSAA on Windows. Support is historically partial and version-sensitive.
• Ordinary buffer text insertion and deletion typically produce toolkit accessibility change notifications; overlay-only changes, including before-string and after-string, may not generate separate screen-reader events.
• No stable, documented core Elisp API is known for forcing a synchronous accessibility-tree refresh during rapid mutation.

Likely explanation

The accessibility bridge observes buffer-level changes through the GUI toolkit, not the overlay list. Because an overlay is a display-layer annotation, the bridge may treat it as cosmetic and skip it when building the OS accessibility tree. Rapid mutation compounds the problem because toolkit notifications are usually coalesced, so screen readers may announce nothing or announce stale state.

Steps for this case

1. Prefer real buffer text or text properties over purely graphical overlays when the meaning must be announced. Insert visible annotation text, or use text properties with a face and announce the change through your installed speech bridge if one is present.
2. If an overlay must remain visual-only, pair it with a short, screen-reader-visible buffer string that updates when the overlay state changes.
3. Group related buffer edits so the toolkit emits fewer discrete change notifications, and avoid triggering redisplay after every character. Do not assume a synchronous accessibility update hook exists.
4. Test on the exact target build before relying on behavior. Open the platform accessibility inspector while toggling an overlay: AT-SPI/AccProbe on Linux, Accessibility Inspector on macOS, or Inspect on Windows. Check whether an accessible object or event appears.
5. Compare screen-reader output for a normal text insertion against an overlay-only change during rapid mutation to confirm whether updates are coalesced or delayed.

Missing diagnostic

I need your Emacs platform/build and version (GTK, NS, or W32) because the exposure path and available variables differ by toolkit. Share your build identification so I can narrow the recommendation.

Verification

Run M-x describe-variable to inspect accessibility-related variables in the running Emacs and confirm the active toolkit backend. Then use the platform inspector to toggle an overlay and observe whether any accessibility object or event appears.