[PR #436] [CLOSED] feat(core): add accessibility API with cross-platform TUI speech #534

New issue

Closed

opened 2026-03-02 23:46:57 +03:00 by kerem · 0 comments

kerem commented

2026-03-02 23:46:57 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/anomalyco/opentui/pull/436
Author: @muhammedaksam
Created: 12/22/2025
Status: ❌ Closed

Base: main ← Head: feat/accessibility

📝 Commits (6)

da1e45e feat(core): add accessibility API layer (#423)
208757d feat(core): add cross-platform TUI accessibility (#423)
8e153ed Merge branch 'main' into feat/accessibility
d928bc8 Merge branch 'main' into feat/accessibility
778092b Merge branch 'main' into feat/accessibility
bf37dcf Merge branch 'main' into feat/accessibility

📊 Changes

6 files changed (+868 additions, -1 deletions)

View changed files

➕ packages/core/docs/accessibility.md (+112 -0)
📝 packages/core/src/Renderable.ts (+120 -1)
➕ packages/core/src/examples/accessibility-demo.ts (+260 -0)
➕ packages/core/src/lib/AccessibilityManager.ts (+257 -0)
📝 packages/core/src/lib/index.ts (+1 -0)
➕ packages/core/src/tests/accessibility.test.ts (+118 -0)

📄 Description

Fixes #423

Summary

Add AccessibilityManager with cross-platform text-to-speech for TUI accessibility
Implement accessibility properties on Renderables (role, label, value, hint, hidden, live)
Support announcements and focus tracking with automatic speech output
Works with native platform TTS without requiring screen reader integration

Changes

AccessibilityManager.ts: Add node tracking, event handling, cross-platform TTS
Renderable.ts: Add accessibility properties (role, label, value, hint, hidden, live)
lib/index.ts: Export AccessibilityManager and getAccessibilityManager
examples/accessibility-demo.ts: Interactive demo with focus announcements
docs/accessibility.md: API documentation with platform requirements
tests/accessibility.test.ts: Unit tests for AccessibilityManager

Platform Support

Platform	TTS Method	Requirements
Linux	spd-say	speech-dispatcher, espeak-ng
Windows	SAPI	PowerShell (built-in)
macOS	say	Built-in

Testing

bun test packages/core/src/tests/accessibility.test.ts
bun run packages/core/src/examples/accessibility-demo.ts

Notes

My first approach was based on @kommander's RFC in the issue - implementing native accessibility infrastructure (AT-SPI2 D-Bus for Linux, UI Automation COM for Windows, NSAccessibility for macOS) to directly integrate with screen readers like Orca/NVDA/VoiceOver.

However, this approach is challenging for TUI applications because:

TUI apps run inside terminal emulators (gnome-terminal, Windows Terminal, iTerm2)
The terminal emulator owns the native window, not the TUI app
Screen readers interact with the terminal's accessibility layer, not apps running inside

Without owning a native GUI window, registering with platform accessibility APIs (creating an HWND for UIA, connecting to AT-SPI2 registry, etc.) isn't straightforward. The implemented solution uses direct TTS calls which works immediately for TUI apps and provides accessibility announcements without needing native window ownership.

Tested on Linux (spd-say) and Windows (SAPI). macOS (say command) is untested but should work as the implementation is straightforward.

Open to suggestions for improving the accessibility implementation or adding additional features!

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/anomalyco/opentui/pull/436 **Author:** [@muhammedaksam](https://github.com/muhammedaksam) **Created:** 12/22/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/accessibility` --- ### 📝 Commits (6) - [`da1e45e`](https://github.com/anomalyco/opentui/commit/da1e45ec5f5116047400b4f7371caa7901be88b2) feat(core): add accessibility API layer (#423) - [`208757d`](https://github.com/anomalyco/opentui/commit/208757d061207a7b51e9c199986ba61de1db5790) feat(core): add cross-platform TUI accessibility (#423) - [`8e153ed`](https://github.com/anomalyco/opentui/commit/8e153edd6eb8dcb9ecba28319ef54bd8e380c3e5) Merge branch 'main' into feat/accessibility - [`d928bc8`](https://github.com/anomalyco/opentui/commit/d928bc8f5d27a45377fb6e6af64ad8df03a2f80d) Merge branch 'main' into feat/accessibility - [`778092b`](https://github.com/anomalyco/opentui/commit/778092bd1eb0a38a304fe0bcb02d8f6f827fbc5d) Merge branch 'main' into feat/accessibility - [`bf37dcf`](https://github.com/anomalyco/opentui/commit/bf37dcfc5127e221e8e61c4b07e326d392d34e99) Merge branch 'main' into feat/accessibility ### 📊 Changes **6 files changed** (+868 additions, -1 deletions) <details> <summary>View changed files</summary> ➕ `packages/core/docs/accessibility.md` (+112 -0) 📝 `packages/core/src/Renderable.ts` (+120 -1) ➕ `packages/core/src/examples/accessibility-demo.ts` (+260 -0) ➕ `packages/core/src/lib/AccessibilityManager.ts` (+257 -0) 📝 `packages/core/src/lib/index.ts` (+1 -0) ➕ `packages/core/src/tests/accessibility.test.ts` (+118 -0) </details> ### 📄 Description Fixes #423 ## Summary - Add `AccessibilityManager` with cross-platform text-to-speech for TUI accessibility - Implement accessibility properties on Renderables (role, label, value, hint, hidden, live) - Support announcements and focus tracking with automatic speech output - Works with native platform TTS without requiring screen reader integration ## Changes - `AccessibilityManager.ts`: Add node tracking, event handling, cross-platform TTS - `Renderable.ts`: Add accessibility properties (role, label, value, hint, hidden, live) - `lib/index.ts`: Export AccessibilityManager and getAccessibilityManager - `examples/accessibility-demo.ts`: Interactive demo with focus announcements - `docs/accessibility.md`: API documentation with platform requirements - `tests/accessibility.test.ts`: Unit tests for AccessibilityManager ## Platform Support | Platform | TTS Method | Requirements | |----------|-----------|--------------| | Linux | spd-say | speech-dispatcher, espeak-ng | | Windows | SAPI | PowerShell (built-in) | | macOS | say | Built-in | ## Testing ```bash bun test packages/core/src/tests/accessibility.test.ts bun run packages/core/src/examples/accessibility-demo.ts ``` ## Notes My first approach was based on @kommander's [RFC in the issue](https://github.com/sst/opentui/issues/423#issuecomment-3667009602) - implementing native accessibility infrastructure (AT-SPI2 D-Bus for Linux, UI Automation COM for Windows, NSAccessibility for macOS) to directly integrate with screen readers like Orca/NVDA/VoiceOver. However, this approach is challenging for TUI applications because: 1. TUI apps run inside terminal emulators (gnome-terminal, Windows Terminal, iTerm2) 2. The terminal emulator owns the native window, not the TUI app 3. Screen readers interact with the terminal's accessibility layer, not apps running inside Without owning a native GUI window, registering with platform accessibility APIs (creating an HWND for UIA, connecting to AT-SPI2 registry, etc.) isn't straightforward. The implemented solution uses direct TTS calls which works immediately for TUI apps and provides accessibility announcements without needing native window ownership. Tested on Linux (spd-say) and Windows (SAPI). macOS (`say` command) is untested but should work as the implementation is straightforward. Open to suggestions for improving the accessibility implementation or adding additional features! --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>