react-x11 2.51.1 → 2.53.0

package/docs/accessibility.md

@@ -0,0 +1,575 @@
+# Accessibility
+
+react-x11 applications are visible to screen readers. The renderer carries a
+built-in [AT-SPI2](https://gitlab.gnome.org/GNOME/at-spi2-core) bridge — the
+interface GTK and Qt register through — so Orca reads a react-x11 window like
+any other: roles, names, states, focus, live text editing, and the actions
+that drive controls without a pointer. It is on by default; with no
+accessibility bus the bridge never comes up, and the render path pays one
+property read per event.
+
+> **Per backend.** On **win32** the same tree is pushed to UI Automation
+> instead ([windows.md](windows.md#accessibility-ui-automation)). On
+> **Cocoa** there is no bridge yet: `createRoot()` leaves AT-SPI off there
+> (`desktop: { a11y: false }` by default) and a Cocoa-backend app is not
+> reachable by VoiceOver. Write `role`, `aria-*` and `announce()` anyway:
+> they live on the shared node tree, and an `NSAccessibility` bridge will
+> read them unchanged.
+
+```jsx
+<box role="button" aria-label="Close" onClick={close} focusable>
+  <text>×</text>
+</box>
+```
+
+That is the entire API for most code. `role` and `aria-*` are the web's
+names, accepted on every host element — the vocabulary react-dom takes — so
+a component library that sets them is accessible here with no
+react-x11-specific knowledge, and the built-in widgets (`Button`,
+`Checkbox`, `Select`, `Menu`, `Tabs`, …) already carry them.
+
+Design notes: [design/architecture/accessibility.md](../design/architecture/accessibility.md)
+(no mirror tree, the web's vocabulary, what was rejected) and
+[design/accessibility.md](../design/accessibility.md).
+
+## What a screen reader hears without any props
+
+Accessibility is not opt-in; an unlabelled tree is _boring_ to a screen
+reader rather than broken:
+
+| element                 | reads as                                                    |
+| ----------------------- | ----------------------------------------------------------- |
+| `<window>`              | frame, named by `title`                                     |
+| `<popup>`               | window (give the content a `role` — `menu`, `dialog`, …)    |
+| `<box>`                 | filler — skipped silently, like GTK's own layout boxes      |
+| `<text>`                | label, reading its content — and its selection, if any      |
+| `<textinput>`           | entry: editable, single-line, caret and selection live      |
+| `<textarea>`            | entry: editable, multi-line                                 |
+| `<image>` / `<svg>`     | image, named by `alt`                                       |
+| `overflow: 'scroll'`    | scroll pane (and a tab stop when it can scroll — see below) |
+| `<canvas>` / `<glarea>` | drawing area / canvas — name them if they carry meaning     |
+
+Focus, enabled/disabled, checked, selected, expanded and the rest are read
+from the same live state the widgets draw from — the `focusable` rule, the
+`disabled` prop, the `aria-*` props — so what the screen reader says cannot
+drift from what the screen shows.
+
+## The props
+
+All of these are accepted on every host element and are inert (and
+harmless) when no assistive technology is listening.
+
+| prop                                                        | AT-SPI meaning                                       |
+| ----------------------------------------------------------- | ---------------------------------------------------- |
+| `role`                                                      | what the element _is_ (ARIA role names; table below) |
+| `aria-label`                                                | the accessible name, over every other source         |
+| `aria-description`                                          | supplementary description                            |
+| `aria-hidden`                                               | remove this subtree from the accessible tree         |
+| `aria-checked` (`true`/`false`/`'mixed'`)                   | CHECKABLE + CHECKED / INDETERMINATE                  |
+| `aria-selected`                                             | SELECTABLE + SELECTED                                |
+| `aria-expanded`                                             | EXPANDABLE + EXPANDED / COLLAPSED                    |
+| `aria-pressed`                                              | PRESSED (toggle buttons)                             |
+| `aria-busy`, `aria-modal`, `aria-required`, `aria-readonly` | the states of the same names                         |
+| `aria-haspopup`                                             | HAS_POPUP (`'menu'`, `'listbox'`, `'dialog'`, …)     |
+| `aria-orientation`                                          | HORIZONTAL / VERTICAL                                |
+| `aria-valuenow` / `-valuemin` / `-valuemax` / `-valuetext`  | the Value interface (sliders, progress)              |
+| `aria-level`, `aria-posinset`, `aria-setsize`               | "level 2", "3 of 7" — headings, trees, lists         |
+| `aria-keyshortcuts`                                         | the shortcut announced with the item ("Control+N")   |
+| `onAccessibilityAction`                                     | the AT drove the control (below)                     |
+
+Roles: `alert alertdialog article banner blockquote button caption cell
+checkbox columnheader combobox comment complementary contentinfo dialog
+document form grid gridcell group heading img link list listbox listitem log
+main marquee math menu menubar menuitem menuitemcheckbox menuitemradio meter
+navigation note option paragraph progressbar radio radiogroup region row
+rowheader scrollbar search searchbox separator slider spinbutton status
+switch tab table tablist tabpanel term textbox timer toolbar tooltip tree
+treegrid treeitem window`, plus `none`/`presentation` to erase a wrapper
+from the accessible tree while keeping its children. An unknown role warns
+in development and falls back to the element default — a typo neither turns
+a button into a filler nor crashes.
+
+There is no `aria-disabled`: use `disabled`, which blocks focus and drives
+`:disabled` style blocks, so the two cannot disagree. There is no
+`aria-labelledby`/`aria-describedby` either: there are no element ids to
+point them at — use `aria-label`, or lean on name-from-contents.
+
+### Names
+
+The accessible name resolves in order: `aria-label` → what the element
+itself carries (a window's `title`, an image's `alt`, an input's
+`placeholder`) → for roles whose contents are their label (buttons,
+checkboxes, menu items, tabs, links, options, tree items, …), the visible
+text inside. So `<Button>Save</Button>` is named "Save" with nobody writing
+a label.
+
+### AT-driven controls
+
+Activation needs no wiring: every element whose role promises it (button,
+checkbox, menu item, tab, …) or that has an `onClick` exposes an AT-SPI
+`activate` action. The bridge performs it as a synthetic click through the
+normal event path — capture, bubble, default actions, the discrete-priority
+commit — so Orca pressing a button is indistinguishable from a pointer. It
+is a full press gesture (mousedown, mouseup, click), because `Select` and
+`MenuBar` open their menus on the press.
+
+**The keyboard shares that click.** Space and Enter on a focused element with
+an `onClick` dispatch the same gesture through the same function
+([events.md](events.md#space-and-enter-are-a-click)). A role _advertises_
+an action to an AT that cannot press a key; a `role="button"` with no
+`onClick` has no click for a key to trigger.
+
+The one thing that needs a handler is a _value_ write — Orca adjusting a
+slider through the Value interface. The handler receives one argument:
+
+```ts
+{ action: 'setValue', value: number }
+```
+
+`'setValue'` is the only action delivered today (`action` is a string so
+the shape can grow; activation never arrives here). Wire it into the same
+state setter as the pointer and the keyboard:
+
+```jsx
+<box
+  role="slider"
+  aria-valuenow={value}
+  aria-valuemin={0}
+  aria-valuemax={100}
+  onAccessibilityAction={({ action, value }) => {
+    if (action === 'setValue') setValue(clamp(value));
+  }}
+/>
+```
+
+`Slider` already does exactly this.
+
+### Announcements
+
+```js
+import { announce } from 'react-x11';
+
+announce('Form saved');
+announce('Connection lost', { assertive: true });
+```
+
+The explicit counterpart of an ARIA live region: say something through the
+screen reader without moving focus. Returns `true` when a bridge was live
+to carry it; `false` means nobody is listening and a visible fallback may
+be warranted. Orca ≥ 45 speaks these. There is no `aria-live` region
+tracking — an explicit call cannot fire on renders you did not mean.
+
+## What the built-in widgets announce
+
+Every widget in [components.md](components.md) is wired; none of them need
+anything from you beyond their ordinary props. What a screen reader hears:
+
+| widget                    | reads as                                                                         |
+| ------------------------- | -------------------------------------------------------------------------------- |
+| `Button`                  | button, named by its label; disabled buttons say so                              |
+| `Checkbox`                | check box, checked/unchecked, named by its label                                 |
+| `Radio` / `RadioGroup`    | radio buttons with the selected one checked                                      |
+| `Switch`                  | switch, on/off — **give it an `aria-label`**, it has no visible label of its own |
+| `Slider`                  | horizontal slider with value and range; Orca can adjust it                       |
+| `ProgressBar`             | progress bar, its value as a percentage of its range; `indeterminate` is busy    |
+| `Select`                  | combo box named by the current choice, expanded/collapsed; its menu is a listbox |
+| `MenuBar` / `ContextMenu` | menu bar and menus (below)                                                       |
+| `Tooltip`                 | tooltip                                                                          |
+| `Dialog`                  | modal dialog, named by its title                                                 |
+| `Tabs`                    | tab list with orientation; each tab selected or not; the panel is a tab panel    |
+| `Table`                   | table with column headers and rows ("n of m", selected)                          |
+| `SplitPane`               | the divider is a separator with orientation and position (ARIA window splitter)  |
+
+An `indeterminate` `ProgressBar` reports no value rather than 0%. A
+`Select`'s options each read "n of m", the current one selected. Menu items
+carry their shortcut as the standard `keyshortcuts` attribute ("Control+N" —
+UI Events spelling, where the row draws "Ctrl+N" and the key path
+[binds it](events.md#accelerators)), a `toggleType` as checked/radio,
+`toggleState: -1` as `mixed`, and submenus as expandable. A virtualized
+`Table` has only its rendered rows in the tree — the same rows a sighted
+user can see.
+
+## Text controls
+
+`<textinput>` and `<textarea>` implement the AT-SPI `Text` and
+`EditableText` interfaces in full: character count, reading by
+character/word/line, caret position (offsets are code points, on both
+sides), selections, per-character screen rectangles for magnifiers and
+caret tracking, and edits — a screen reader can read, navigate, select,
+and type. Every edit and caret move emits the precise
+`text-changed`/`text-caret-moved` deltas Orca narrates from.
+
+Limit: "line" granularity follows hard newlines, not the soft wraps of a
+`<textarea>`'s layout. Orca still reads everything; a line-by-line walk of
+one long wrapped paragraph is one stop, not several.
+
+A `<text>` has the `Text` interface too — readable, with no caret — and
+reports its **selection**: a paragraph inside a `selectable` surface
+([elements.md](elements.md#selecting-text)) hands over the range the user
+has dragged across, and says so as it moves, so a magnifier's highlight and
+a braille display's cursor sit on the highlighted characters.
+
+### While a composition is open
+
+A dead key or a half-typed Compose sequence puts text on the screen that is
+in nobody's value yet ([events.md](events.md#composition)). The `Text`
+interface answers with **what is drawn**, that preedit included, and its
+offsets index that string, so a magnifier tracking a character lands on the
+glyph a sighted user sees. `CaretOffset` is at the far end of the
+composition, where the next keystroke of the sequence appears.
+
+The uncommitted part is marked twice:
+
+- as its own **attribute run** — `underline: single` (the registered AT-SPI
+  attribute) plus `composition: true` (this renderer's own; AT-SPI
+  registers nothing for a preedit);
+- as **`:system`** text — `text-changed:insert:system` when the accent
+  appears, `delete:system` when it changes or is abandoned — which lets a
+  reader stay quiet through a composition.
+
+What the sequence **commits** is a plain `insert` of the finished
+character: `é` is spoken once, as one insertion — the same event an
+ordinary keystroke produces, and one undo step.
+
+Nothing here goes through `announce()` (the screen reader would say the
+accent twice); an application that wants to narrate composition state can
+call `announce()` itself from `onCompositionUpdate`.
+
+### Text of your own
+
+A [registered element](extending.md) that draws its own text — a code
+editor, a markdown viewer, a terminal, a canvas-backed table with cell
+editing — reports it through one method and is then read by everything
+above: character count, reading by character/word/line, caret, selection,
+the text-changed deltas, and an AT that can navigate and type.
+
+```js
+class EditorNode extends Node {
+  a11yTextState() {
+    return {
+      value: this.text, // what is drawn, composition included
+      caret: this.caret, // code-point offsets into `value`
+      selectionStart: this.anchor,
+      selectionEnd: this.caret,
+      editable: true, // an editor rather than a viewer
+      multiline: true,
+    };
+  }
+
+  insert(text) {
+    /* …the edit… */ this.notifyA11yTextChanged();
+  }
+}
+```
+
+| member                              |                                                                                                     |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `a11yTextState()`                   | `{ value, caret, selectionStart, selectionEnd, editable, multiline, preedit }` — `null` for no text |
+| `notifyA11yTextChanged()`           | the text moved. Free when nothing is listening, so no guard around it                               |
+| `a11ySetSelection(start, end)`      | an AT moved the caret or made a selection                                                           |
+| `a11yReplaceText(start, end, text)` | an AT edited — insert, delete and replace all arrive as this                                        |
+| `a11yRole`                          | the role the element is when the app writes none; `role` still wins                                 |
+
+Two tiers. `{ value, selectionStart, selectionEnd }` alone is a document:
+the `Text` interface, a `document` role, a selection an AT reads and sets —
+all a markdown view with Ctrl+C needs. `editable: true` adds the EDITABLE
+state, an `entry` role and, once `a11yReplaceText` exists, the
+`EditableText` interface. An element that reports editable text but
+implements no write is announced as editable and reports its own edits, but
+is not offered to an AT to type into.
+
+Offsets are code points and index the string the element **draws** — an
+open composition included, as with `<textinput>`. Report the uncommitted
+part as `preedit: { offset, text }` and its churn is marked `:system`, so a
+reader stays quiet through a dead key and speaks the character it commits.
+Offsets are clamped on the way out, so a stale caret cannot become an
+out-of-range answer.
+
+Known limits, none of which stop a screen reader working: per-character
+screen rectangles fall back to the element's own rect (a magnifier tracks
+the element, not the glyph), and AT-driven paste and copy are the
+built-ins' — an element's own Ctrl+C/Ctrl+V is unaffected.
+
+The test spy observes this seam exactly as it observes core's, so an editor
+in another package can assert what it says with no bus and no desktop —
+[below](#asserting-what-a-screen-reader-would-hear).
+
+### A scene of your own
+
+A [registered element](extending.md) that _draws_ interactive things — a
+graph pane, a chart, a timeline, a seating plan — is one node, so it is one
+accessible: "Flow graph, group", with three hundred selectable nodes inside
+it that no assistive technology can see. It says what it drew and each one
+becomes a child:
+
+```js
+class FlowNode extends Node {
+  a11yScene() {
+    return this.nodes.map((node) => ({
+      id: node.id, // stable while it is on screen: this is identity
+      role: 'listitem',
+      name: node.label,
+      rect: node.rect, // window coordinates
+      states: {
+        selected: this.selection.has(node.id),
+        focused: this.cursor === node.id,
+      },
+    }));
+  }
+
+  select(id) {
+    /* …the element's own selection… */ this.notifyA11ySceneChanged();
+  }
+}
+```
+
+| member                        |                                                                                                       |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `a11yScene()`                 | `[{ id, rect, role, name, description, focusable, states, props, children }]`                         |
+| `notifyA11ySceneChanged()`    | the scene moved between commits — a drag, an animation, your own arrow keys                           |
+| `a11ySceneAction(id, action)` | an AT sent `'activate'`, `'focus'` or `'scroll'`. `true` claims it; anything else keeps core's answer |
+
+`role` and the `aria-*`-shaped states become the AT-SPI role and state set,
+`rect` becomes the Component extents a magnifier tracks and focus is drawn
+around, and a change to any of it is announced as that child changing
+rather than as the pane being replaced. Keyboard navigation _between_ items
+stays the element's own — the window's focus manager holds the element, so
+`states.focused` is the only way the cursor inside it is reported.
+
+Activation with no `a11ySceneAction` is a synthetic click at the item's own
+rect, which is what a mouse user does to it; the seam is for elements where
+that is not the truth. See
+[extending.md](extending.md#a-scene-a-screen-reader-can-walk) for the whole
+contract.
+
+## The compatibility ladder
+
+`createRoot()` starts one climb per process, off the critical path:
+
+1. is `dbus-native` installed? (it is an optionalDependency; Node < 22.12
+   skips it)
+2. is there a session bus?
+3. does `org.a11y.Bus` answer `GetAddress`? (this also starts the a11y bus
+   launcher on desktops where it is not running yet)
+4. connect, export the tree, `Embed` with the AT-SPI registry.
+
+Every "no" is a normal, **silent** off: ssh sessions, CI, containers, bare
+`startx`, macOS and Windows X servers have no accessibility stack, and the
+app does not log, slow down or change behaviour because of it. The bridge
+holds no event-loop reference, so a process that is done exits; the
+registry sees the name drop and forgets the app.
+
+Environment switches, in priority order:
+
+- `REACT_X11_A11Y=0` — off. Any other value forces the climb **and makes
+  it loud**: each rung prints why it stopped, which is the answer to "why
+  does Orca not see my app", and the bridge says when it goes quiet and when
+  it wakes ([with nobody listening](#with-nobody-listening)).
+- `AT_SPI_BUS_ADDRESS` — skip discovery and connect here. The seam
+  sandboxes use, and the one the hermetic tests use.
+- `REACT_X11_A11Y_INTERVAL=<ms>` — how often changes are pushed to the
+  platform, 500 by default; `0` pushes every change. See
+  [How often the bridge speaks](#how-often-the-bridge-speaks), which also
+  applies to the Windows bridge.
+- `NO_AT_BRIDGE=1` — off; the ecosystem-wide switch every toolkit honours.
+  `react-x11/test` sets it, so a test run on a desktop does not parade
+  phantom applications through a running screen reader.
+
+To turn the bridge off from the app itself, without a variable every child
+process inherits:
+
+```jsx
+await createRoot({ desktop: { a11y: false } });
+```
+
+It outranks every switch above, `REACT_X11_A11Y=1` included — see
+[desktop.md](desktop.md#turning-the-desktop-off), where `desktop: false` turns
+this off along with the other two integrations that talk to the session bus.
+Pass it on the first root: the climb happens once per process, and a second
+root's switch cannot unstart a bridge that is already up.
+
+A dead accessibility bus is not redialled — the same contract as
+[dbus.md](dbus.md): the app stops being accessible until restarted.
+
+## How often the bridge speaks
+
+Both bridges (AT-SPI and UI Automation) pace what they push, the way
+browsers do, so a scroll, a pan or a ticking value does not pay for a
+platform update on every commit:
+
+- **A change after a quiet spell is pushed at once.** A click or a key that
+  changes one thing is heard immediately.
+- **A stream of changes is pushed at most once per interval**, 500 ms by
+  default, and the last push carries the last state. A row that scrolls in
+  and out between two pushes is never exported at all, and an AT that was
+  never told of it is not told it left.
+- **What the user is waiting on is pushed at once, whatever the interval:**
+  focus moving, an announcement, and a change to the focused element itself,
+  such as the characters typed into it or its toggled state.
+- **Reads are never paced** (AT-SPI). A call from an AT first flushes
+  whatever the pacer is holding, so every object and interface it asks
+  about is as the tree has it now. Only the unsolicited signals wait.
+
+`REACT_X11_A11Y_INTERVAL` sets the interval in milliseconds, and `0` goes
+back to a push per change.
+
+### With nobody listening
+
+An AT-SPI bus runs in most Linux sessions whether or not a screen reader
+does, so the bridge asks the registry who is listening. A listener is an AT
+that registered for events, or any client other than the registry that
+calls in.
+
+- **With no listener and no caller, the bridge falls silent.** Nothing is
+  queued, pushed or exported, and what it had exported before the registry
+  answered is withdrawn. The tree still answers every read, starting from the
+  application root.
+- **The first listener or the first call wakes it for good.** The AT reads
+  the tree as it is, which is where it would start anyway, and every change
+  after that is pushed as above.
+- **An announcement made during the silence goes unheard**, and
+  `announce()` returns `false` for it, as it does with no bridge at all.
+- **A registry that cannot say who listens** is taken to have someone
+  listening, as GTK 4 does with one it cannot ask.
+
+## For component libraries
+
+There is nothing to integrate against. Set the standard props on the host
+elements you render, exactly as the built-in widgets do; the bridge mirrors
+whatever the tree says. The seams, in increasing order of involvement:
+
+- `role` + `aria-*` on any element — the whole story for almost everything.
+- `disabled`, `focusable`, `tabIndex` — already doubling as the ENABLED and
+  FOCUSABLE states; nothing separate to maintain.
+- `onAccessibilityAction` — when an AT can _set_ something on your control.
+- A [registered element](extending.md) is a host element like any other:
+  its instances take all of the above, and a class that should default to a
+  role assigns `this.a11yRole` in its constructor (a `role` prop still
+  wins).
+- `a11yTextState()` + `notifyA11yTextChanged()` — when your element draws
+  text of its own, which is the one thing props cannot express
+  ([above](#text-of-your-own)).
+- `a11yScene()` + `notifyA11ySceneChanged()` — when your element draws
+  interactive _things_ of its own, which is the other one
+  ([above](#a-scene-of-your-own)).
+
+## Testing and verifying
+
+### Asserting what a screen reader would hear
+
+`renderX11(element, { a11y: true })` hands back `at`, an in-process
+assistive-technology spy: the same semantic feed the AT-SPI bridge serves
+to Orca, observed before it becomes D-Bus — so it is synchronous, needs no
+bus, and runs everywhere the test suite runs (the mock backend, Node 20,
+macOS included). Input stays real: `userEvent.tab()` is a Tab through the
+in-process X server's focus machinery, not a shortcut around it.
+
+```js
+import { renderX11, userEvent, cleanup, XK_SPACE } from 'react-x11/test';
+
+const { at } = await renderX11(<Preferences />, { a11y: true });
+
+await userEvent.tab();
+assert.equal(at.focused().utterance, 'Save, button');
+
+await userEvent.tab();
+await userEvent.key(XK_SPACE);
+assert.ok(at.since().some((e) => e.type === 'state' && e.state === 'checked'));
+```
+
+Every entry is a precise fact (`{ type, state, on, node, … }`) plus a
+one-line `summary`; `at.transcript()` is the summaries, made for
+`deepEqual`. `at.focused()` and `at.focusables()` describe nodes the way an
+AT would — name, role, states, and an `utterance` string following the
+model on this page (name, role, the states worth speaking, a value as a
+percentage). The utterance is **this library's model, not an imitation of
+Orca**, whose wording is presentation policy; a control nobody named
+renders as `"(no accessible name)"` instead of passing because no assertion
+happened to mention its name.
+
+Four tests worth copying into any application — each one a check a sighted
+test author cannot make by looking (`test/a11y-spy.test.js` in the
+repository is the worked example of all four):
+
+- **Focus order** — tab through, `deepEqual` the focus summaries.
+- **No keyboard trap** — `at.focusables().length` + 1 Tabs lands back on
+  the first stop, and Shift+Tab wraps the other way.
+- **Nothing nameless** — for each of `at.focusables()`, assert the
+  utterance is not `"(no accessible name)"`. The highest value per line on
+  this page.
+- **State changes are announced** — press Space on a checkbox, assert a
+  `checked` state entry arrived; a widget that repaints without one is the
+  most common accessibility regression there is.
+
+### Testing the bridge itself
+
+The wire half is testable without a desktop too: point
+`AT_SPI_BUS_ADDRESS` at an in-process bus (dbus-native's broker), own
+`org.a11y.atspi.Registry` on it with a stub `Embed`, and walk your app with
+real D-Bus calls — `test/atspi.test.js` is the worked example, and the
+model half (roles, names, states as pure functions over the tree) needs no
+bus at all (`test/a11y.test.js`). Applications rarely need this layer.
+
+### Seeing it without learning a screen reader
+
+`npm run a11y:probe`, from a checkout of the react-x11 repository, is the
+client side of AT-SPI — the side Orca is on — with no GNOME libraries and
+nothing to configure:
+
+```bash
+npm run a11y:probe                       # what is on the accessibility bus
+npm run a11y:probe -- widgets            # dump that app's accessible tree
+npm run a11y:probe -- widgets --watch    # follow its events as you click
+npm run a11y:probe -- widgets --watch --speak   # ...said out loud
+npm run a11y:probe -- nautilus           # someone else's toolkit, for comparison
+```
+
+Point it at a GTK app and at yours: if the shapes match, a screen reader
+will treat them the same. The `say:` lines it prints are a **toy** model,
+not what Orca utters, but they make a missing accessible name audible
+instead of merely absent.
+
+### With a real screen reader
+
+```bash
+orca --replace --debug-file=/tmp/orca.log     # then Tab through your app
+grep "SPEECH OUTPUT" /tmp/orca.log
+```
+
+The debug log is the ground truth, and it is easier to read than listening.
+For audio, speech-dispatcher does the talking (`spd-say hello` tests it on
+its own). Orca's own toggle is `gsettings set
+org.gnome.desktop.a11y.applications screen-reader-enabled true`; the GUI
+inspector, if you want one, is `accerciser`.
+
+### Scripting the AT side
+
+The AT stack is also scriptable through the same library Orca uses:
+
+```python
+import gi; gi.require_version('Atspi', '2.0')
+from gi.repository import Atspi
+desktop = Atspi.get_desktop(0)
+apps = [desktop.get_child_at_index(i) for i in range(desktop.get_child_count())]
+app = next(a for a in apps if a and a.get_name() == 'myapp')
+# walk it, read roles/names/states, do_action(0), set values…
+```
+
+Under `react-x11/test` the bridge is off by default (`NO_AT_BRIDGE`), so
+tests stay deterministic.
+
+## What is deliberately not there (yet)
+
+- **Relations** (`aria-labelledby`, label-for) — use `aria-label` or
+  name-from-contents.
+- **The Selection interface** on containers — per-item SELECTED states are
+  exposed, and selection is driven through actions and focus.
+- **The Table interface** — `Table` exposes `table`/`row`/`cell` roles with
+  positions, but not the row/column navigation calls; only rendered rows
+  exist in the accessible tree.
+- **Key-event forwarding** (`DeviceEventController.NotifyListenersSync`) —
+  typed characters arrive through text-changed events.
+- **Soft-wrap line granularity** in `<textarea>`, per above.
+- **An input method** — dead keys and Compose are the whole composition
+  story, so a script that needs a candidate window (any CJK) cannot be
+  typed.