[FEATURE] - Accessibility: Notify bookmark presence and states to screen readers

[mcking65]

Environment/version

• Extension version: 14.1.1
• VSCode version: 1.133.0 (user setup)
• OS version: Microsoft Windows 11 Professional Version 25H2 (OS Build 26200.9168)

Steps to reproduce

1. Turn on a screen reader, such as VoiceOver on macOS or Narrator on Windows
2. Open an editor in VSCode with the Bookmarks extension installed.
3. Execute the command bookmark.toggle
4. Arrow down to the next line
5. Arrow back up to the line with the bookmark.
6. Execute the command bookmark.toggle

Expected Behavior

1. When the bookmark is added, a non-visual notification informs the user.
2. When the cursor moves to the line containing the bookmark, a non-visual indicator informs the user of the presence of the bookmark.
3. When the bookmark is removed, a non-visual notification informs the user.

Actual Behavior
A blind user is not aware of any of the events.

Problem Description

As a blind user who is using a screen reader, such as JAWS, NVDA, VoiceOver, or Narrator, and who must rely on the keyboard instead of the mouse, the bookmarks extension could be particularly valuable because of the many different ways it enables navigation and selection. However there are some important tasks that are preventing me from tapping its real productivity enhancing potential.

it is difficult to:

1. Know what has happened when I execute the bookmark toggle command.
2. Know if the current line contains a bookmark.

If I understand the documentation correctly, visual users are able to perceive these states and state changes without taking extra actions, such as opening and inspecting the bookmark list. For now, using the list is my primary means of working around these gaps. It is a pretty cumbersome workaround.

Solution Proposal

Could you please leverage the VSCode accessibility infrastructure to:

1. Add bookmarkToggleAccessibilityNotification: If accessibilityModeEnabled, generate an accessibility notification when the toggle bookmark command is executed.
2. Add settings/accessibility.signals.lineHasBookmark: If accessibilityModeEnabled, generate an accessibility alert when the cursor moves to a line containing a bookmark.

bookmarkToggleAccessibilityNotification Details

A good model for this is the behavior of the command editor.action.setSelectionAnchor. When accessibility mode is enable, that command generates and accessibility notification that tells me that a selection anchor was set and where. Another example is the command editor.action.announceCursorPosition, which generates an accessibility notification about the current position of the cursor in the editor.

I recommend that when the result of command bookmarks.toggle is:

• bookmark is added: send notification "Mark set at line Y column X"
• Bookmark is removed: send notification "Removed mark from line Y column X"

Note: I recommend this specific phrasing so the two strings:

• Sound as distinct as possible, i.e., the word "mark" is in different positions.
• Are as short as possible while still providing all critical information, i.e., "bookmark" is shortened to "mark".

Caveat: I don't know if the above characteristics would be well preserved when translated.

settings/accessibility.signals.lineHasBookmark Details

A good model for this is accessibility.signals.diffLineInserted. When navigating a diff and the cursor moves to a line that was inserted, this causes a specific sound to be played.

The tricky part of this signal is including an appropriate sound. The sound needs to be short, distinct from other accessibility signals, and noticeable without being overly intrusive.

One way to help users understand the meaning of the signal sound would be to play the sound when a bookmark is added; this would be in addition to sending the notification string. This would generate an immediately understandable association between the signal sound and the presence of a bookmark.

[alefragnani]

Hi @mcking65,

Thanks for the detailed report and proposal.

I looked into the VS Code extension API to see what's available for this, and unfortunately there isn't currently a way for extensions to trigger non-visual screen reader announcements the way built-in commands like editor.action.setSelectionAnchor do. That behavior relies on an internal aria.alert() module in VS Code core that is not exposed through the extension API (vscode.d.ts), and there is also no contribution point allowing extensions to register custom entries under accessibility.signals.*.

This has already been requested upstream in microsoft/vscode#114718 "Allow extensions to aria announce", which proposed essentially the same aria.announce(message) API described here. That issue was closed by the VS Code team as out of scope — they decided not to add a generic announcement API for extensions, citing concerns that screen readers should ideally react to focus changes and live regions rather than an arbitrary "announce this" call, and worry about extensions overusing it.

Given that, implementing #1 (toggle notifications) and #2 (line-has-bookmark signal) as described isn't something we can support today without VS Code exposing the right API. I'd recommend upvoting/commenting on #114718 (or opening a fresh, more scenario-specific request referencing this use case) to help make the case upstream. We'll keep this issue open and revisit if/when such an API becomes available.

Hope this helps.

[mcking65]

@alefragnani

Thank you for investigating so promptly.

I will provide feedback to the VSCode AX team about their decision; I think they should support extensions integrating their accessibility settings into the native accessibility architecture and extending native capability.

While I was assuming such extension was already possible, these features are possible without VSCode exposing any of those APIs.

Instead of using accessibility signals, wouldn't It be feasible to add extension-specific settings to play sounds for events? There could be two settings: one to turn the event sound on/off and another to set the sound file to use.

In addition, Chromium now supports Element: ariaNotify(). I don't know if that means electron supports it; I would hope so.

BTW, we wouldn't want to use live regions to send strings to screen readers if it could be avoided for this type of notification. While it is possible, ariaNotify() would be far superior because it doesn't require adding any nodes to the DOM.

So, wouldn't it be possible to have extension-specific settings that turn on/off sending a string via ariaNotify for each of the events? Then, for each one, another setting that enables the user to customize the string, which would be particularly important for people who want to customize the string to a language that is not supported by default.

[alefragnani]

Hi @mcking65,

Thanks for following up with these alternative ideas — I looked into both.

1. Extension-specific settings to play sounds on events

Unfortunately, there's no VS Code extension API (stable or proposed) that lets an extension play a sound file or register a custom entry into the native accessibility.signals.* system. Technically an extension could shell out via Node.js to an OS-level sound player (e.g. afplay on macOS, similar on Windows/Linux), but that's not an official API — it would mean bundling/locating sound files and reimplementing playback per-OS outside VS Code's supported extension surface, which isn't something I'd want to build into Bookmarks.

The good news: there's already an open upstream request for exactly this — microsoft/vscode#175986 "Allow VS Code extensions to trigger audio cues" — and Bookmarks has already been mentioned there as a use case. The VS Code team has shown some interest but wants to design it carefully (e.g. extensions contributing semantic audio cues that plug into the user's existing sound-pack/signal settings, rather than arbitrary raw sound files) — no committed timeline yet.

2. Element.ariaNotify() instead of live regions

This is a newer Web API, but it wouldn't help here even as a workaround: extensions only have direct DOM access inside their own Webviews (which are sandboxed), not VS Code's own editor UI. Calling ariaNotify() inside a Webview would only announce within that Webview's own accessibility tree — not to the editor where bookmarks actually live. There's no proposed API exposing VS Code's internal aria.alert/aria.status module (or an ariaNotify-based equivalent) to extensions, and the reasoning behind the earlier decline of #114718 (screen readers should react to focus/live regions, not an arbitrary "announce this" call) would likely apply the same way here.

So for now, both alternatives are still blocked upstream. I'd recommend upvoting/commenting on #175986 with your specific bookmark use case, since that's the most active and relevant thread for this kind of feature. I'll keep this issue open and revisit if that API materializes.

Hope this helps.