react-x11 2.51.1 → 2.52.0

package/docs/accessibility.md

@@ -0,0 +1,628 @@
+# 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
+same interface GTK and Qt applications register themselves through — so Orca
+reads a react-x11 window the way it reads any other: roles, names, states,
+focus, live text editing, and the actions to drive controls without a
+pointer.
+
+It is on by default and costs nothing to have: with no accessibility bus on
+the machine the bridge never comes up, and the render path pays one property
+read per event for the hooks it would have filled.
+
+> **This is the Linux bridge; the win32 backend has one of its own and Cocoa
+> has none.** On **win32** the same tree is pushed to UI Automation instead
+> (`src/win32/a11y.js`, [windows.md](windows.md#accessibility-ui-automation)),
+> because UIA asks synchronously and is answered from a pushed copy rather
+> than from the live tree. AT-SPI
+> is a freedesktop protocol with nothing to register against on macOS, so on
+> the **Cocoa** backend `createRoot()` leaves it off (`desktop: { a11y:
+false }` by default there) and no `NSAccessibility` bridge has been built
+> in its place — a Cocoa-backend app is not yet reachable by VoiceOver.
+> Everything else on this page still earns its keep there: `role`, `aria-*`
+> and `announce()` are properties of the shared node tree, keyboard
+> traversal and the widgets' own semantics are shared code, and all of it is
+> what an `NSAccessibility` bridge will read when it lands
+> ([macos.md](macos.md), Phase 5). Write them now; nothing changes when it
+> does.
+
+```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 same vocabulary react-dom takes
+and React Native adopted — 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.
+
+> This page is the reference. The design record — why there is no mirror
+> tree, why the vocabulary is the web's rather than React Native's, why
+> discovery dials its own socket, what was rejected and what is deferred —
+> is [architecture/accessibility.md](architecture/accessibility.md).
+
+## What a screen reader hears without any props
+
+Accessibility is not opt-in; the defaults are chosen so 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 must not
+silently turn a button into a filler, and it must not crash either.
+
+Two deliberate absences. There is no `aria-disabled`: `disabled` is already
+a host prop with real behaviour (it blocks focus and drives `:disabled`
+style blocks), and a parallel prop that only _said_ disabled would let the
+two disagree. And there is no `aria-labelledby`/`aria-describedby`: 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` — the fallback the web engines also use) → 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, and
+`announce`-worthy custom controls need one prop, not three.
+
+### AT-driven controls
+
+Activation needs no wiring at all: every element whose role promises it
+(button, checkbox, menu item, tab, …) or that has an `onClick` exposes an
+AT-SPI `activate` action, and the bridge performs it by dispatching 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 finger.
+
+(Under the hood the activation is a full press gesture — mousedown, mouseup,
+click — because several controls act on the press: `Select` and `MenuBar`
+drop their menus on it, the way real menus do.)
+
+**The keyboard shares that click.** Space and Enter on a focused element with
+an `onClick` dispatch the same gesture through the same function, so a
+keyboard user and a screen-reader user are never served differently by the
+same element — see [events.md](events.md#space-and-enter-are-a-click). The
+role half of the rule above stays the AT's: a role _advertises_ an action to
+something that cannot press a key, and a `role="button"` with no `onClick`
+has no click for a key to be.
+
+The one thing that does need a handler is a _value_ write — Orca adjusting
+a slider through the Value interface. The handler receives one argument:
+
+```ts
+{ action: 'setValue', value: number }
+```
+
+(`action` is a string so the shape can grow; `'setValue'` is the only
+action delivered today — activation never arrives here, it goes through the
+event system above.) 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 is smaller, and it 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; the value reads as a percentage of its range, and an `indeterminate` one is busy with no value rather than 0%                                                                                                                                                                         |
+| `Select`                  | combo box named by the current choice, expanded/collapsed; its menu is a listbox of options, each "n of m" and the current one selected                                                                                                                                                             |
+| `MenuBar` / `ContextMenu` | menu bar and menus; 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`, submenus as expandable |
+| `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). Virtualization means only rendered rows exist in the tree — the same rows a sighted user can see                                                                                                                                           |
+| `SplitPane`               | the divider is a separator with orientation and position — the ARIA window-splitter pattern                                                                                                                                                                                                         |
+
+## Text controls
+
+`<textinput>` and `<textarea>` implement the AT-SPI `Text` and
+`EditableText` interfaces in full working order: 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.
+
+One honest 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 to move.
+What it now also reports is 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 same
+characters the highlight is painted over.
+
+### 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 — because every geometric answer beside it is
+read off the layout of the same string, and a magnifier tracking character
+3 has to land on the glyph a sighted user sees. `CaretOffset` is at the far
+end of the composition, where the next keystroke of the sequence appears.
+
+Which part of it is uncommitted is said twice, so a reader can act on
+either:
+
+- the preedit is its own **attribute run** — `underline: single`, the
+  registered AT-SPI attribute for what is literally drawn, plus
+  `composition: true`, which is this renderer's own because AT-SPI
+  registers nothing for a preedit;
+- its churn is **`:system`** text — `text-changed:insert:system` when the
+  accent appears, `delete:system` when it changes or is abandoned. That is
+  the suffix Gecko established for a change the user did not type, and it
+  is what lets a reader stay quiet through a composition.
+
+What the sequence **commits** is a plain `insert` of the finished
+character: `é` is what the user typed, and it is spoken, once, as one
+insertion — the same event an ordinary keystroke produces, which is also
+why it is one undo step and not two.
+
+Nothing here is announced through `announce()`. A live-region announcement
+on top of the text-changed feed would have a screen reader 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, because the read-only one is a real element and not a
+degenerate editor. `{ value, selectionStart, selectionEnd }` alone is a
+document: the `Text` interface, a `document` role, a selection an AT reads
+and sets — which is what a markdown view with Ctrl+C needs and all it
+needs. `editable: true` adds the EDITABLE state, an `entry` role and, once
+`a11yReplaceText` exists, the `EditableText` interface. Nothing is exposed
+that would not work: 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 as one to type into.
+
+Offsets are code points and index the string the element **draws** — an
+open composition included, for the same reason `<textinput>`'s do. Report
+which part is uncommitted 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 on the wire.
+
+The known limits of the tier, 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. Both
+want a layout the element alone has; say so on the issue if you have one.
+
+The seam is observed by the test spy exactly as core's is, 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
+
+The other half of the same gap. 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 |
+
+They are read by the same model everything else is: `role` and the
+`aria-*`-shaped states above 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, which is why
+`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 exactly what a mouse user does to it; the seam is for the
+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 — react-x11's own flagship
+configurations — simply have no accessibility stack, and an app must not
+log, slow down or grow a mode because of it. The bridge holds no
+event-loop reference either, 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.
+
+And one that is not environmental, for an app that has to turn the bridge off
+for itself without setting a variable every child process will inherit:
+
+```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 simply stops being accessible until restarted.
+
+## How often the bridge speaks
+
+A bridge mirrors the tree for a platform that reads it on its own schedule,
+and pushing the mirror on every commit is paid by everything that commits
+often: a scroll, a pan, a value ticking. That was mostly paid for nobody.
+An AT-SPI bus runs in most Linux sessions whether or not a screen reader
+does, and a 100,000-row `<Table>` flung through it exported, diffed and
+unexported every row that scrolled past: 31 frames a second against 38 with
+the bridge off. On Windows the same push was 1.6 ms of every frame of a
+graph pane's pan. So both bridges pace what they push (`src/a11ypace.js`),
+the way browsers do. Chromium batches non-interactive accessibility updates
+150 ms apart once a page has loaded, and bounds 500 ms apart, and serializes
+focus and selection at once.
+
+- **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
+
+Pacing bounds what a push costs. It does not help when nobody hears the
+push, which is the usual case: the bus runs whether or not a screen reader
+does. Dragging a scrollbar thumb down a 100,000-row `<Table>` ran at 19
+frames a second with the AT-SPI bridge on and 24 with it off, and nothing on
+that desktop was listening. So the bridge asks the registry.
+
+An AT registers the events it wants with the registry. The registry answers
+`GetRegisteredEvents` and announces each new listener, and GTK 4 and
+at-spi2-atk use that to hold back the events nobody asked for. Both still
+send the cache's signals and `children-changed` regardless, because libatspi
+listens for those in every client without registering. So an empty list is
+not the whole answer. An AT that registered for nothing still has to call in
+to read anything, and a call from anybody but the registry counts too.
+
+- **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 documented on this page (name, role, the states worth speaking, a
+value as a percentage). The utterance is deliberately **this library's
+model, not an imitation of Orca**, whose wording is presentation policy;
+what it buys you is that 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` 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 in
+  this document.
+- **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; it
+is how react-x11 proves the transport.
+
+### Seeing it without learning a screen reader
+
+`npm run a11y:probe` 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
+```
+
+It talks to whatever is on the bus, so pointing it at a GTK app and at
+yours is the sharpest check available: if the shapes match, a screen reader
+will treat them the same. The `say:` lines it prints are a **toy** model —
+what Orca really utters is Orca's own policy — but they make a missing
+accessible name audible instead of merely absent, which is the failure that
+matters most and is easiest to miss.
+
+### 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…
+```
+
+Accerciser gives the same view interactively, and running `orca` while
+Tab-walking your app is the ground truth. Under `react-x11/test`,
+remember, the bridge is off by default (`NO_AT_BRIDGE`) so tests stay
+deterministic.
+
+## What is deliberately not there (yet)
+
+- **Relations** (`aria-labelledby`, label-for) — needs an id registry;
+  `aria-label` and name-from-contents cover the widgets.
+- **The Selection interface** on containers — Orca reads per-item
+  SELECTED states and selection is driven through actions and focus, so
+  this is polish, not a gap in coverage.
+- **The Table interface** — `Table` exposes honest `table`/`row`/`cell`
+  roles with positions, but not the row/column navigation calls; note that
+  virtualization means only rendered rows exist in the accessible tree,
+  which is also all a sighted user can see.
+- **Key-event forwarding** (`DeviceEventController.NotifyListenersSync`) —
+  Orca's per-keystroke echo of _keys themselves_; typed characters already
+  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 today, so a script that needs a candidate window (any CJK) cannot
+  be typed at all, accessibly or otherwise. What an IME would report is
+  already here: the preedit is a text run and its own `:system` feed, so
+  the work left is the input method, not its accessibility.