react-x11 2.51.0 → 2.52.0

package/docs/events.md

@@ -0,0 +1,1025 @@
+# Events
+
+ntk delivers raw X11 events per window; react-x11 turns them into synthetic
+events dispatched over the drawn node tree with DOM-like semantics.
+
+## Dispatch
+
+1. **Hit test**: front-to-back walk of the stacking-ordered tree (zIndex,
+   then document order), respecting `overflow` clipping and
+   `pointerEvents` — `'none'` takes a node and everything in it out of the
+   test, `'box-none'` only the node itself, so its children are still
+   targets and a point over its own area lands on what is behind it. A
+   `<glarea>` is asked first: its surface is stacked above everything 2D in
+   the window, and its children above the surface, so a point over one lands
+   on the child under it or on the `<glarea>` — or, with `'box-none'`, on
+   whatever the tree has behind the surface
+   ([elements.md](elements.md#glarea)).
+2. **Capture phase**: `on<Event>Capture` handlers from the window down to
+   the target.
+3. **Target + bubble phase**: `on<Event>` handlers from the target up.
+4. **Default action**: the element's built-in behavior (textinput editing,
+   wheel scrolling, then Tab traversal) — skipped if any handler called
+   `ev.preventDefault()`.
+
+Step 4 is a documented seam, not a privilege of the built-in elements: an
+element added with `registerElement` implements the same `defaultKeyDown` /
+`defaultMouseDown` / `defaultMouseMove` / … methods and gets the same
+ordering ([extending.md](extending.md#behaviour-of-your-own)). The wheel has
+one more layer than the rest: the node under the pointer gets `defaultWheel`
+first — for a pane whose wheel is a zoom rather than a scroll — and unless it
+consumes the event, the scroll chain walks outward from the target asking
+each node `canScroll(deltaX, deltaY)`, which is how an element that scrolls
+content it painted joins in
+([extending.md](extending.md#scrolling-content-you-painted)).
+
+`ev.stopPropagation()` stops the walk. Handlers always read from current
+props — they can never go stale.
+
+### When the response is painted
+
+**Discrete input paints from its own handler**, in the same turn of the
+event loop as the press — not on the next frame. A click has exactly one
+visual answer (a button darkens, a caret lands, focus moves), so there is
+nothing a frame's wait could coalesce it with, and waiting would charge it
+up to a frame interval plus a server round trip on top of a paint that
+measures in the hundreds of microseconds. The dispatcher therefore lands
+React's discrete-priority commit and paints once the whole dispatch has
+unwound — the default action, your handlers and React's update all in one
+pass, never a half-updated frame followed by a second one.
+
+Discrete means everything ntk does not coalesce: `mouseDown`/`mouseUp`,
+`keyDown`/`keyUp`, focus and blur, and the window manager's close request.
+
+**Motion and the wheel stay on the frame clock.** `mouseMove`, and the hover
+enter/leave work it drives, are the opposite case — the pointer reports at
+device rate and only the newest position matters — so they coalesce to at
+most one repaint per frame. A scroll is the same case for a different reason:
+a touchpad reports one dozens of times a frame, and nobody can see those
+frames apart. What makes the wait free is that ntk coalesces a scroll by
+_adding it up_ rather than keeping the newest, so a frame's event carries the
+whole distance and the pacing costs a paint, never a pixel.
+
+**Hover follows content.** A scroll moves content under a pointer that did
+not move, and so can a layout that reflows it. After a frame that laid out
+— every frame of a scroll does — the window asks again what is under the
+pointer's last position, as a browser asks at the frame after a scroll:
+`:hover`, `onMouseEnter` and `onMouseLeave` change as a motion would change
+them, and the node under the pointer hears `defaultMouseMove` at that point,
+so an element that paints its own hover (a document, a graph) re-reads what
+it is over. `onMouseMove` is not called — the pointer did not move — and
+nothing changes while a press or a capture holds the pointer, or after the
+pointer has left the window.
+
+**Hover belongs to the active window, on macOS.** Nothing in CSS or the
+DOM ties hover to focus — `:hover` is "while the user designates an element
+with a pointing device", and a `mousemove` is owed whenever the pointer moves
+over an element — but the platform does. A window there that is not the
+active one does not track the pointer: AppKit's own controls roll over in
+the key window alone, and a browser drops the moves over a window that is
+neither key nor main and tells the page the pointer left. So on the Cocoa
+backend a window that loses the keyboard hears `onMouseLeave` down its hover
+path, `:hover` comes off, an element that paints its own hover hears
+`defaultMouseLeave`, and no motion, enter, cursor or attention follows until
+the window is the active one again — when the hover comes back at the point
+the pointer is at, without waiting for it to move. `<window onMouseOut>` is
+not called: the pointer is still over it.
+
+"Active" is the focus's answer, as it is for the caret
+([below](#window-focus)): a window whose `<Dialog>` holds the keyboard still
+hovers. A `<popup>` nothing manages — a menu, a dropdown, a popover under a
+tray item — always does, since it is on the screen because the user asked
+for it, in an application that may have no active window at all. A press
+still lands where it was aimed, as the first click on a window always has
+here, and its gesture runs on; the wheel scrolls a background window as the
+platform has it. On X11, Wayland and Windows nothing changes: every toolkit
+there hovers in a window without the keyboard, and with focus-follows-mouse
+the question hardly arises.
+
+Bursts of discrete input stay bounded by the same mechanism. While the
+server has not acknowledged the last frame, the response goes back to the
+paced path: click twice quickly and the first press paints immediately while
+the second folds into one catch-up frame. Update instantly, then catch up.
+
+This needs ntk 5.2.0 or newer, which publishes the `frameInFlight()` gate
+the decision is made with. On an older ntk everything still works; the
+response simply waits for the next frame, as it did before.
+
+### When a handler throws
+
+**No error boundary can catch it.** A boundary only sees throws React
+itself invoked, and a handler runs from an X event, so React is not on the
+stack. react-x11 therefore catches it at the dispatcher: the error is
+reported with the element, the handler name and the component that rendered
+the node, `process.exitCode` is set to 1 so the crash is still visible to CI
+and to a supervisor, and **dispatch continues** — one bad tooltip handler
+must not stop the handlers after it, or the frame loop.
+
+```
+react-x11: onClick on <box> in Panel threw. It ran from an X event rather
+than a render, so no error boundary could catch it; dispatch continues.
+```
+
+`onDrop` is the one handler that may be `async`, and a promise it rejects
+with arrives here too — same message, same channel — rather than becoming an
+unhandled rejection, which node exits on. It also refuses the drop; see
+[drag-and-drop.md](drag-and-drop.md#the-drop).
+
+`createRoot({ onUncaughtError })` takes it over completely, which is the
+point of it being overridable: for a kiosk, crashing loudly is correct.
+
+```js
+const root = await createRoot({
+  onUncaughtError: (error, info) => {
+    telemetry.report(error, info.componentStack);
+    process.exit(1);
+  },
+});
+```
+
+## Event object
+
+```
+{
+  type, target, currentTarget,      // public instances
+  x, y,                             // window coordinates
+  localX, localY,                   // target-relative
+  nativeEvent,                      // the raw ntk/X11 event
+  shiftKey, ctrlKey,                // on every event, not just keys
+  altKey, metaKey,                  // Mod1 and Mod4 — see Modifiers below
+  preventDefault(), stopPropagation(),
+  capturePointer(), releasePointer(),   // see Pointer capture below
+  // mouse: button, detail (DOM-style click count: 2 = double, 3 = triple)
+  // wheel: deltaX, deltaY (pixels), smooth
+  // keyboard: keycode, keysym, group, codepoint, key, composing
+  // composition: data
+}
+```
+
+`ev.screenX`/`screenY` are where the pointer is on the virtual screen, in the
+same logical pixels `ev.x`/`y` are in — what to anchor a `<popup>` at, since
+`<popup x y>` are logical too. Undefined on an event with no pointer position.
+
+`nativeEvent.rootx/rooty` is the same point in **device** pixels, which is the
+unit a node's `abs` is in — reach for it when doing geometry against `abs`,
+and for nothing else. The split is the same one `ev.x` and `nativeEvent.x`
+have (docs/scale.md).
+
+`detail` counts a press as the next of a multi-click when it lands within the
+desktop's double-click time and distance of the last one
+([system.md](system.md#usedesktopsettings--how-the-desktop-wants-an-app-to-feel)),
+and the gap is the one between the times the two presses carry,
+`nativeEvent.time`, not between when each was handled. So a first click
+whose render outlasts the window still makes a double click with a second
+the user pressed in time. Presses that carry no time (win32's) are timed as
+they are handled.
+
+On the Wayland backend a finger or a tablet tool drives the same mouse
+events, and those events alone carry `nativeEvent.pointerType` (`'touch'`,
+`'pen'`, `'eraser'` or `'mouse'`) with `pressure`, `tiltX`/`tiltY`,
+`rotation`, `distance` and `tangentialPressure` in the DOM's ranges; a mouse
+adds nothing, so a handler that never looks is unaffected. Every finger also
+arrives raw on the window as `touchstart`/`touchmove`/`touchend`/
+`touchcancel` (`wnd.on(...)`, not React props) — see
+[wayland-backend.md](wayland-backend.md).
+
+`x`/`y`/`localX`/`localY` and the wheel deltas are logical pixels in **the
+target's** unit — the display scale, times any `scale` prop above it
+([scale.md](scale.md#a-subtree-of-its-own)). With no `scale` in the tree
+that is one unit for the whole window; with one, a handler on an unzoomed
+ancestor is reading the zoomed target's pixels, and `ev.nativeEvent.x`/`y`
+are the way back to the window's own.
+
+**A Ctrl chord is read from the keysym, not the code point.** `codepoint`
+comes from the _shifted_ keysym, so Ctrl+Shift+Z arrives as `Z` and Ctrl+Z as
+`z`; a handler that compares code points misses half of its own shortcut.
+`ctrlChordLetter(ev)` from `react-x11/keysyms` answers with the lowercase
+keysym either way — it is what `<textinput>` reads Ctrl+C/V/Z with, and it is
+exported because any widget with a chord of its own needs the same rule:
+
+```js
+onKeyDown={(ev) => {
+  if (ev.ctrlKey && ctrlChordLetter(ev) === keysymOf('d')) duplicateLine();
+}}
+```
+
+That keeps working under a Cyrillic or Greek layout too: `ev.keysym` is the
+Latin keysym for the key however the layout is switched — see
+[Layouts](#layouts). For a chord an application would otherwise write out by
+hand, [Accelerators](#accelerators) is the shorter way: a menu item's
+`shortcut` already binds itself, and `useAccelerator` takes the same chord.
+
+### Modifiers
+
+Four booleans, DOM names, on **every** event rather than only the keyboard
+ones — a shift+click, an Alt+drag and a Super+wheel all need them:
+
+| property   | X11 modifier | usually |
+| ---------- | ------------ | ------- |
+| `shiftKey` | Shift        | Shift   |
+| `ctrlKey`  | Control      | Ctrl    |
+| `altKey`   | Mod1         | Alt     |
+| `metaKey`  | Mod4         | Super   |
+
+```js
+onKeyDown={(ev) => {
+  if (ev.altKey && ev.keysym === keysymOf('b')) wordLeft();
+}}
+```
+
+**Mod1 is Alt and Mod4 is Super by convention, not by protocol.** X says
+only that there are eight modifier rows and lets the keymap decide which
+keys sit in each; those two are where `setxkbmap` puts Alt and Super, and
+where every toolkit — GTK and Qt included — reads them from. The setup that
+disagrees still has the raw mask: `ev.nativeEvent.buttons` is the state
+field as it arrived, and `MOD` in `react-x11/keysyms` names its bits
+(`MOD.Mod3`, `MOD.Lock` for Caps Lock, and so on).
+
+### The primary modifier {#primary-modifier}
+
+**On the Cocoa backend the editing chords are ⌘, not Ctrl.** ⌘ arrives as
+`metaKey` (the DOM's own macOS mapping), and the app says which of the two its
+shortcuts are pressed with: `app.primaryModifier` is `'Super'` there and absent
+everywhere else, X11 under XQuartz included. The built-in editors read it, so
+`<textinput>`'s Undo, Cut, Copy, Paste and Select All are ⌘Z, ⌘X, ⌘C, ⌘V and
+⌘A on a Mac, Redo is ⇧⌘Z, and the right-click menu prints them that way. A ⌃
+or ⌘ chord the field has no answer for is never typed as text — AppKit hands
+over the key's bare character with either held. A widget with chords of its
+own asks the same question with `primaryModifierHeld`:
+
+```js
+import { ctrlChordLetter, keysymOf, primaryModifierHeld } from 'react-x11/keysyms';
+
+onKeyDown={(ev) => {
+  if (primaryModifierHeld(ev, app) && ctrlChordLetter(ev) === keysymOf('d'))
+    duplicateLine();
+}}
+```
+
+It is the same rule a menu bar's `shortcut` follows there, where `Control`
+means ⌘ ([globalmenu.md](globalmenu.md#shortcuts-are-a-list-not-a-string)),
+and the one [accelerators](#the-chord) follow: `useAccelerator([['Control',
+'K']])` is ⌘K on a Mac, and a drawn `ContextMenu` prints and answers `⌘S`.
+
+The editing keys follow it as well. Where shortcuts are ⌘, `<textinput>` and
+`<textarea>` move and delete the Mac's way — AppKit's own bindings, the table
+every Cocoa field reads — so a Mac user's hands already know them:
+
+| keys                   | does                                                                        |
+| ---------------------- | --------------------------------------------------------------------------- |
+| ⌥← ⌥→                  | a word back or forward                                                      |
+| ⌘← ⌘→, and ⌃← ⌃→       | the start or end of the line                                                |
+| ⌘↑ ⌘↓                  | the start or end of the value                                               |
+| ⌥↑ ⌥↓                  | the start or end of the paragraph, and on to the next                       |
+| ↑ ↓ in a `<textinput>` | its start and its end, as in an NSTextField                                 |
+| ⌥⌫ ⌥⌦                  | delete a word                                                               |
+| ⌘⌫                     | delete to the start of the line                                             |
+| ⌃⌫                     | take the accent off the character before the caret — é to e                 |
+| ⌃A ⌃E                  | the start or end of the paragraph                                           |
+| ⌃B ⌃F, ⌃P ⌃N           | a character back or forward, a line up or down                              |
+| ⌃H ⌃D                  | delete a character back or forward                                          |
+| ⌃K ⌃Y                  | kill to the end of the paragraph — its break, at its end — and yank it back |
+
+Shift extends the selection with every move. "Line" is the line as it is
+drawn, wrapped, and "paragraph" runs between line breaks; in a
+`<textinput>` both are the whole value.
+
+Everywhere else the bindings are GTK's, Qt's and Windows': Ctrl+←/→ and
+Ctrl+⌫/⌦ by word, Ctrl+A to select all. The two sets disagree about Ctrl
+outright — ⌃← is the start of the line on a Mac, and ⌃A the start of the
+paragraph — so a backend has one set or the other, never a mix. Home and
+End move the caret to the ends of the line on every backend: AppKit scrolls without moving it, which a field — one
+line, its caret the point of the keystroke — has no use for.
+
+⌃K's kill buffer is the application's and not the pasteboard, as it is in
+AppKit: a kill leaves what ⌘C copied alone, ⌃Y in one field yanks what ⌃K
+killed in another, and kills one after another add up, so the two that take
+a line and then its break yank back as the line. A `sensitive` field kills
+into nothing, for the reason it offers no Copy.
+
+Any of them is the field's default action, so an `onKeyDown` that calls
+`preventDefault()` keeps the key, as it does every other.
+
+## Handlers
+
+| handler                                                           | notes                                                                                                                                                       |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onClick`                                                         | fires on the nearest common ancestor of press & release; `detail` counts multi-clicks                                                                       |
+| `onMouseDown` / `onMouseUp` / `onMouseMove`                       | move is coalesced to once per frame by ntk                                                                                                                  |
+| `onMouseEnter` / `onMouseLeave`                                   | do not propagate; synthesized by hover-path diffing, on motion and when a scroll moves content under a still pointer                                        |
+| `onWheel`                                                         | pixels, from the device or from X buttons 4–7; default action scrolls the nearest scroll container with somewhere to go                                     |
+| `onContextMenu`                                                   | right-click (button 3), after `onMouseDown`; default action opens the element's menu                                                                        |
+| `onKeyDown` / `onKeyUp`                                           | delivered to the focused node (or the window); Space/Enter click an `onClick`, [accelerators](#accelerators) fire and Tab cycles focus, unless it took them |
+| `onCompositionStart` / `onCompositionUpdate` / `onCompositionEnd` | text still being typed — a dead key, a Compose sequence; see below                                                                                          |
+| `onFocus` / `onBlur`                                              | focus follows mousedown (nearest `focusable` ancestor) and Tab traversal                                                                                    |
+| `onDragEnter` / `onDragLeave`                                     | do not propagate; drag-path diffing, the same shape as the hover pair above                                                                                 |
+| `onDragOver` / `onDrop`                                           | on a drop target; `onDrop` may be async — [drag-and-drop.md](drag-and-drop.md)                                                                              |
+| `onDragStart` / `onDrag` / `onDragEnd`                            | on a `draggable` node; the press is a click until it moves 4px                                                                                              |
+
+## Space and Enter are a click {#space-and-enter-are-a-click}
+
+**An `onClick` on a focusable node is operable from the keyboard, with
+nothing else written.** Space or Enter on it dispatches the click — the whole
+press gesture, mousedown then mouseup then click, through the ordinary path —
+so a control hand-built out of a `<box>` behaves like a `<Button>`:
+
+```jsx
+<box focusable role="option" aria-selected={on} onClick={() => open(channel)}>
+  <text>{channel}</text>
+</box>
+```
+
+The keys are a **default action**, which is the whole of the contract:
+
+- `preventDefault()` in the node's own `onKeyDown` takes the key back — that
+  is how a widget that answers Enter with something other than its click
+  (a disclosure opens a branch; the click only moves the selection) keeps it;
+- a node with no `onClick` is untouched, whatever its `role` says. A role
+  advertises an action to an assistive technology, which has no other way to
+  ask; a key press is already at the node, so there is nothing to advertise
+  and nothing to activate. `role="button"` with only an `onKeyDown` stays
+  yours;
+- `<textinput>` and `<textarea>` never activate: their own `defaultKeyDown`
+  answers the keystroke, so Space types a space;
+- **a scroll pane keeps Space.** Space and Shift+Space page a scrolling `<box>`
+  ([elements.md](elements.md#scrolling)) — that is a default action too, and
+  the pane answers it before this one, so a clickable pane pages with Space
+  and activates with Enter. A focusable row _inside_ a pane is not affected
+  either way: default actions run on the focused node, and the pane is not
+  it;
+- **a chord is not a press.** With Ctrl, Alt or Super held — ⌘ or ⌃ or ⌥ on
+  the Cocoa backend — Space and Enter are a command, and the node leaves them
+  to whoever bound it: a menu's Ctrl+Return fires with focus on a clickable
+  box exactly as it does anywhere else ([accelerators](#accelerators)).
+
+Shift is not a command, and it travels: the synthesized click carries the key
+press's own modifier mask, so Shift+Enter reaches `onClick` as a shift-click.
+
+It is the same function an assistive technology's activation goes through, on
+purpose — one definition of "activate" for the pointer, the keyboard and
+Orca, which cannot then disagree about a control
+([accessibility.md](accessibility.md#at-driven-controls)).
+
+## Accelerators {#accelerators}
+
+**A menu's `shortcut` is a binding.** `MenuBar` and `ContextMenu` answer their
+own items' chords while they are mounted, so the array that draws the menu is
+the array that binds it:
+
+```jsx
+<MenuBar
+  menus={[
+    {
+      label: 'File',
+      items: [
+        { label: 'Save', shortcut: [['Control', 'S']], onSelect: save },
+        {
+          label: 'Save As…',
+          shortcut: [['Control', 'Shift', 'S']],
+          onSelect: saveAs,
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+Ctrl+S calls `save()` without the menu being opened. The same array is what
+`aria-keyshortcuts` announces and what crosses the bus when the desktop's
+panel draws the menu ([globalmenu.md](globalmenu.md)) — and it stays bound in
+that case, because the panel draws the rows but the key is pressed in your
+window and nothing else is going to deliver it. (The macOS menu bar is the
+exception, and answers the ⌘ chords it shows by itself —
+[below](#the-macos-menu-bar).)
+
+For a shortcut that is not in a menu — there are always some —
+`useAccelerator` takes the same chords, so one can be moved into or out of a
+menu without being rewritten:
+
+```jsx
+import { useAccelerator } from 'react-x11';
+
+useAccelerator([['Control', 'K']], () => openPalette());
+```
+
+### The chord
+
+`[['Control', 'S'], ['F2']]` is dbusmenu's `aas`: a list of **alternatives**,
+each a list of modifier tokens — `Control`, `Alt`, `Shift`, `Super` — ending
+in the key. Any alternative fires; only the first is drawn, since a row has
+one shortcut column.
+
+The key is named the way X names it, which is what `gdk_keyval_name()` emits
+and what a panel's importer parses: `plus` rather than `+`, `Prior` rather
+than `PgUp`, `Return` rather than `Enter`. A one-character name is that
+character. `keysymFromName()` in `react-x11/keysyms` is the resolver, and
+`matchesShortcut(ev, shortcut, { primary })` the matcher, for an application
+dispatching chords its own way.
+
+**`Control` is the app's primary modifier**: Ctrl, except on the Cocoa
+backend, where it is ⌘ — the key a Mac user saves with, the key a drawn row
+prints (`⌘S`, `⇧⌘Z`) and the key the binding answers
+([The primary modifier](#primary-modifier)). `Super` is ⌘ there too, so a
+chord cannot ask for ⌃ on a Mac; a chord is matched with it up. The menus and
+`useAccelerator` read the app's answer themselves, and `matchesShortcut` takes
+it as an option, since it is a pure function with no app to ask:
+
+```js
+import { matchesShortcut } from 'react-x11';
+import { primaryModifier } from 'react-x11/keysyms';
+
+matchesShortcut(ev, [['Control', 'S']], { primary: primaryModifier(app) });
+```
+
+Four rules, all of which a hand-rolled `onKeyDown` gets subtly differently:
+
+- **exact on the four modifiers.** Ctrl+S does not fire on Ctrl+Shift+S.
+- **indifferent to the locks.** Caps Lock and Num Lock are not modifiers here
+  — `ctrlKey`/`altKey`/`shiftKey`/`metaKey` are the four named bits and
+  nothing else, so a chord keeps working with either light on.
+- **the key, not the character.** Matching is against `ev.keysym`, the Latin
+  keysym for the physical key, so a chord survives a layout switch
+  ([Layouts](#layouts)) — and `['Control', 's']` and `['Control', 'S']` are
+  one binding rather than two. A chord that names a **symbol** also matches
+  the character the key produced, because `+` is the shifted `=` and
+  `[['Control', 'plus']]` has to be pressable; letters stay out of that path,
+  since it is exactly what would make Ctrl+Shift+S fire a Ctrl+S binding.
+- **`enabled` and `visible` gate it.** A dimmed item's chord fires nothing,
+  and neither does an item inside a submenu whose parent is disabled — a
+  command you cannot reach by opening the menu is not one a key should reach.
+- **`Control` is the primary modifier**, above — exact on it as on the rest,
+  so ⌃⌘S does not fire a ⌘S binding either.
+
+### Who gets the key first
+
+Accelerators sit at the end of the same default-action chain Tab and
+Space/Enter are in, and `preventDefault()` is the word at every step:
+
+1. the application's own `onKeyDown`, capture then bubble;
+2. composition — a dead key, a Compose sequence;
+3. the focused element's own behaviour (`<textinput>` editing, a scroll pane's
+   page keys);
+4. **accelerators**;
+5. focus traversal, for Tab.
+
+So **a focused text field keeps the chords it answers**: Ctrl+C copies the
+selection and never reaches a menu item that also says Ctrl+C. Ctrl+S is not
+one of the field's, so it falls through to the menu — a control that swallowed
+every chord would be a control no application could put a shortcut behind.
+
+Return is the same rule. A `<textinput>` answers Return and Shift+Return with
+`onSubmit`, and nothing else: Ctrl+Return, Alt+Return and Super+Return — ⌘↩
+on the Cocoa backend — are chords, and reach the menu that prints them. A
+field with **no** `onSubmit` has no answer for Return at all, so the key goes
+on to whatever binds it, a form's `[['Return']]` default button included. A
+`<textarea>` keeps Return and Shift+Return for the newline and Ctrl+Return
+(⌘↩) for `onSubmit` when it has one; Alt and Super on Return are chords there
+too, except on the Cocoa backend, where ⌃↩ and ⌥↩ are AppKit's newline.
+
+Two things suppress them entirely, both because something else has the
+keyboard:
+
+- **an open menu.** It is holding a pointer grab, and a chord firing a second
+  command out from under the one being pointed at is a bug nobody reproduces.
+- **a modal `<popup>`** (`trapFocus`, which is what `Dialog` sets). Ctrl+S
+  while a confirmation is up saves nothing. A menu declared _inside_ the modal
+  still works — the containment rule is the one Tab traversal already follows
+  — and `useAccelerator`'s `scope` option is how a hook-registered shortcut
+  joins it:
+
+  ```jsx
+  const inDialog = useRef(null);
+  useAccelerator([['Control', 'Return']], confirm, { scope: inDialog });
+  ```
+
+A chord belongs to the window whose menu declared it, so a second top-level
+window does not answer it, and `enabled: false` unbinds one without unmounting
+anything. `accelerators={false}` on a `MenuBar` or `ContextMenu` turns the
+whole of this off for an application that already has a dispatcher.
+
+**An app with no `<window>` at all** — a menu-bar app, whose whole UI is the
+popover a tray click opens — binds against the root-level `<popup>` that took
+the keyboard instead
+([elements.md](elements.md#a-popover-under-a-tray-item)). There is nothing
+else for a shortcut to belong to, and it is the window the keys are arriving
+on. A binding that lands on nothing at all — no window and no popup either —
+warns once in development and names `scope`, rather than leaving a chord that
+is drawn, announced and dead.
+
+### The macOS menu bar {#the-macos-menu-bar}
+
+On the Cocoa backend a `MenuBar` is drawn by the system
+([globalmenu.md](globalmenu.md)), which installs each item's chord as an
+`NSMenu` key equivalent where it can spell one — a single chord on a
+character key — and AppKit then runs the item on a ⌘ chord by itself. It does
+so _after_ the window has seen the key, whatever the window did with it. So
+those chords are **reserved**: the window's accelerators are not offered them
+at all, neither the bar's own binding nor a `useAccelerator` on the same
+chord, whichever mounted last, and the item runs once. A chord the menu bar
+cannot spell — a function key, a second alternative, `plus` — or one with no
+`Control` or `Super` in it stays the window's, and fires the way it does
+anywhere else.
+
+The reservation cannot reach steps 1 and 3 above, which run before it: an
+`onKeyDown` that answers ⌘S for itself, or a focused field answering ⌘C beside
+an Edit menu whose Copy says ⌘C, runs alongside the menu item rather than
+instead of it — `preventDefault()` there does not reach AppKit. Leave a chord
+the menu bar shows to the menu bar.
+
+## The wheel {#wheel}
+
+`ev.deltaX` / `ev.deltaY` are **pixels**, positive down and right, and one
+notch of a wheel is 48 of them — the step an arrow key takes, so the two
+input routes move a list by the same amount.
+
+Where the server has XI2, those pixels are the distance the device actually
+measured. The core protocol has no wheel at all: a scroll arrives as a click
+of button 4/5/6/7, and a click carries no magnitude, which is why every
+scroll used to be exactly one notch. XI2 carries the same gesture as the
+device's own _scroll valuators_, so a touchpad's two-finger scroll reports
+the fractions of a notch it really was, and `deltaY` is `14.5` rather than
+`48` twice a second.
+
+```jsx
+<box
+  style={{ overflow: 'scroll' }}
+  onWheel={(ev) => {
+    ev.deltaY; // pixels — fractional from a touchpad
+    ev.smooth; // whether the device can report a fraction at all
+  }}
+/>
+```
+
+`ev.smooth` says which kind of device this was, not whether this particular
+delta happened to be fractional: `true` means the valuators are flowing and
+the next event may be a third of a notch, `false` means the emulated button,
+which can only ever say one. It is the flag to branch on for anything that
+wants to animate a scroll — a whole notch is worth easing towards, a stream
+of measured pixels is not.
+
+**Nothing is opted into.** A `<window>` selects XI2 the first time it is
+scrolled and falls back to the wheel buttons where the server has none, so a
+handler written against `deltaY` works on both and the difference is the
+value. A `<popup>` is on the buttons deliberately — it holds a pointer grab,
+and a core grab delivers core events — so a scroll inside an open menu moves
+a notch at a time. Needs ntk >= 7.5.0.
+
+The selection waits for the first wheel because it is not free. An XI2
+selection _replaces_ the core one for the same event type, and an `XIMotion`
+is around 136 bytes on the wire where a core `MotionNotify` is 32 — measured
+against Xorg 21.1. Motion is the one event that keeps arriving at frame rate
+for as long as the pointer is over the window, so selecting it up front bills
+every window about 8 KB/s of pointer traffic while the pointer crosses it,
+including the dialogs, toolbars and forms that never see a wheel at all.
+
+What waiting costs is the opening event of the first gesture in a window's
+life, and it costs less than it sounds: a mouse wheel reports whole notches
+either way, and ntk treats the first valuator event as a seed with no
+distance to report, so under an eager selection that same first event moves
+nothing at all.
+
+`<window xi2>` selects at creation anyway, for an app whose whole interaction
+is a touchpad and which wants the very first flick smooth. `<window
+xi2={false}>` refuses the selection for the window's whole life.
+
+Shift turns a vertical scroll sideways for a device with only one axis (the
+convention every toolkit follows); a device that reports its own horizontal
+axis keeps what it reported. The default action is the hit node's own
+`defaultWheel` and then the scroll chain — see
+[extending.md](extending.md#behaviour-of-your-own) for the element whose
+wheel is a zoom rather than a scroll, and
+[extending.md](extending.md#scrolling-content-you-painted) for how anything
+joins the chain.
+
+## Composition: dead keys and Compose {#composition}
+
+`é` is not a key. On a French, German or us-intl layout it is `dead_acute`
+then `e`, and a dead key is a keysym with **no code point at all** — so a
+renderer that types from `ev.codepoint` types the letter and drops the
+accent. That is most accented input in Europe, and it is invisible to anyone
+testing on a US layout (issue #272).
+
+A composition is text the user is still typing. It shows at the caret,
+underlined, and it is not the value until it commits:
+
+```
+dead_acute        →  the field shows ´ (underlined). value unchanged.
+e                 →  the field shows é. value is now …é, one undo step.
+```
+
+Everything about it is on by default and needs no configuration:
+
+| you press                          | you get                                           |
+| ---------------------------------- | ------------------------------------------------- |
+| `dead_acute` `e`                   | `é` — and any base letter, in any script          |
+| `dead_circumflex` `dead_acute` `e` | `ế` — dead keys stack                             |
+| `dead_acute` space                 | `´` — the accent on its own                       |
+| `dead_acute` `q`                   | `´q` — no such character, so nothing is swallowed |
+| Compose `o` `c`                    | `©`                                               |
+| Compose `'` `e` (or `e` `'`)       | `é`                                               |
+| Compose `-` `-` `-`                | `—`                                               |
+| Escape mid-sequence                | nothing typed, and the accent goes away           |
+
+The dead keys are Unicode's own composition rather than a table somebody
+maintains, so `dead_breve` + `и` is `й` and `dead_acute` + `α` is `ά`
+without anyone having written those down. What is written down is the part
+Unicode has no rule for: `dead_stroke` + `o` is `ø`, and the `Multi_key`
+symbol sequences, which are conventions rather than compositions.
+
+### Handling it yourself
+
+The three events mirror the DOM's. `data` is empty on the start, the text
+showing at the caret on each update, and the **committed text** at the end —
+empty when the sequence was abandoned.
+
+```jsx
+<textinput
+  onCompositionUpdate={(ev) => setStatus(`composing ${ev.data}`)}
+  onCompositionEnd={(ev) => setStatus('')}
+/>
+```
+
+**A key an open composition took carries no text of its own.** `ev.key` and
+`ev.codepoint` are `undefined` on it and `ev.composing` is true, because its
+text arrives on the composition event instead — an application that types
+from `onKeyDown` would otherwise insert `o`, `c` and then `©`. The keysym is
+still there, so a chord still matches.
+
+The order is **application chords → composition → the element → focus
+traversal**: an `onKeyDown` that calls `preventDefault()` keeps its key and
+the composer never sees it, and a key the composer does take never reaches
+the element's `defaultKeyDown` — so a dead key cannot also fire an
+accelerator, and a Compose sequence containing `z` cannot undo halfway
+through.
+
+A composition is abandoned, never half-committed, when focus leaves, when the
+window loses the keyboard, or when a press puts the caret somewhere else.
+
+A screen reader is told the same story: the preedit is a text run of its
+own and its churn is marked as text the user did not type, so the accent is
+not read out and the character it commits is —
+[accessibility.md](accessibility.md#while-a-composition-is-open).
+
+### Input methods
+
+On the [Wayland backend](wayland-backend.md) the compositor's input method
+(IBus under GNOME) drives the same three events over `zwp_text_input_v3`,
+and on the Windows backend the system IME drives them over IMM32
+(`src/win32/ime.js`): its preedit arrives on `onCompositionUpdate` and the
+text it commits on `onCompositionEnd`, inserted the way a typed character
+is. Two things are only there:
+
+- `ev.cursorBegin` / `ev.cursorEnd` on an update — code-point offsets into
+  `data` — when the engine says where inside its preedit the cursor is, or
+  which segment of a phrase it is converting (drawn with a heavier
+  underline). A dead key never sets them.
+- a commit with no preedit before it — an emoji picker, an engine that
+  commits directly — is a start and an end in one.
+
+Keys the input method consumes never reach the application, so a dead key
+composed by IBus does not also reach the client-side table; a key that does
+arrive is one the input method declined. `<textinput sensitive>` offers the
+input method none of its text, and `inputMode` on a `<textinput>` tells it
+what to expect ([elements.md](elements.md#textinput)).
+
+The **Cocoa backend has no input method yet** — `NSTextInputClient` is
+[macos.md](macos.md)'s IME work — so its text is what each key event says it
+typed. A dead key such as ⌥E types nothing and shows nothing, and the key
+after it types what macOS put on that key: `é` where the event carries the
+dead key's composition, the bare letter where it does not, never the two
+letters reading the key's own character used to type. A key that typed more
+than one character — the accent and a letter it does not combine with, `´s`
+— commits them as one composition, a start and an end in one, the way an
+input method's commit arrives. Press-and-Hold accents and CJK input wait on
+the same work.
+
+### Changing the table
+
+```js
+import { XK_MULTI_KEY } from 'react-x11/keysyms';
+
+const root = await createRoot({
+  compose: {
+    // this machine's Compose file, which is how a personal ~/.XCompose is
+    // picked up — usually absent on macOS, where nothing is lost
+    file: 'system',
+    sequences: [[[XK_MULTI_KEY, 'l', 'd'], '🦆']],
+  },
+});
+```
+
+`compose: 'system'` is the whole file shorthand, `compose: false` turns
+composition off for an app that does its own, and later definitions win over
+earlier ones — which is what makes a Compose file an override of the
+built-ins rather than an addition beside them. Parsing is X's own format;
+`include` directives are ignored, and a line naming keysyms outside ASCII
+and the dead-key block (`<Greek_alpha>`, `<Cyrillic_a>`) is skipped rather
+than guessed at.
+
+**What this is not is an input method.** There is no preedit arriving from
+another process and no candidate list, so CJK still needs XIM or an
+IBus/Fcitx client — issue #272 tracks it. The events above are the surface it
+will arrive on.
+
+## Layouts {#layouts}
+
+A key event answers two questions and, the moment a non-Latin layout is
+active, it has to answer them differently:
+
+- **what the key typed** — `ev.key` and `ev.codepoint`, the active layout,
+  the active level. A Cyrillic layout types Cyrillic.
+- **what the key is called** — `ev.keysym`, the **Latin** keysym for that
+  key, whichever group holds it. Shortcuts do not move with the layout, in
+  GTK, in Qt and in the browsers, and Ctrl+Z has to keep undoing while the
+  user is typing Russian.
+
+So `ctrlChordLetter(ev) === keysymOf('z')` matches the physical Z key under
+every layout, and nothing in a widget has to know that a layout exists.
+
+**⌥ types, on the Cocoa backend.** It is the layout's third and fourth level
+there rather than a modifier: ⌥S is `ß` on a US keyboard, and on a German one
+⌥L is `@` and ⌥5 and ⌥8 are `[` and `{` — the only keys that type them. So
+`ev.key` and `ev.codepoint` are what the layout typed, with ⌥, Shift and Caps
+Lock applied, while `ev.keysym` is still the key (`s`) and `ev.altKey` is
+true: an Alt+S accelerator still matches, and a field types `ß`. A ⌘ or ⌃
+chord types nothing and is named by its key, so ⌘⌥S is a chord on S — the
+same split the DOM makes on a Mac.
+`ev.group` is the active XKB group, 0-3, for an application that wants to
+show which layout is live — a switch sends no other notice.
+
+Where the Latin keysym comes from depends on how the layout got there, and
+the two mechanisms have nothing in common:
+
+- **Linux/XKB** loads every layout at once as a group and switches which one
+  is live; the keymap never changes and **no MappingNotify is sent**. The
+  Latin keysym is on the same keycode, in whichever group is the Latin one —
+  which under `ru,us` is the second.
+- **XQuartz** has no groups. It synthesizes the keymap from the active macOS
+  layout and _overwrites_ it when the input menu changes (Preferences →
+  Input → "Follow system keyboard layout"; without that, nothing downstream
+  can help), then sends MappingNotify. After a switch to Russian **no group
+  anywhere holds Latin**, and the only thing left that still means "the Z
+  key" is the keycode — so that is what is used, against the US position of
+  whichever keycode scheme the server speaks.
+
+```js
+const root = await createRoot({
+  // 'latin' is the default; 'layout' reports the keysym the layout put on
+  // the key, for an app matching shortcuts its own way
+  accelerators: 'layout',
+});
+```
+
+`accelerators` also takes a keycode→keysym table (`{ 52: 'z' }`) for a
+server whose keycodes are neither evdev's nor macOS's, which is the only
+case the two built-in ones do not cover.
+
+One thing the core protocol cannot express is the difference between two
+groups of two levels and one group of four, so **the AltGr row is not
+reachable**: `ev.keysym` and `ev.codepoint` read groups only. Resolving it
+needs XkbGetMap, which node-x11 does not implement.
+
+## Pointer capture
+
+`ev.capturePointer()` routes every following `mousemove` and `mouseup` to
+the capturing node instead of whatever is under the pointer, so a drag
+keeps working past the widget's own bounds — and a release far outside it
+still ends the gesture. This is what `Slider` is built on:
+
+```jsx
+onMouseDown: (ev) => {
+  ev.capturePointer();
+  setDragging(true);
+},
+onMouseMove: (ev) => { if (dragging) setValue(valueAt(ev)); },
+onMouseUp: () => setDragging(false),
+```
+
+Capture is released automatically on `mouseup` (like the DOM's implicit
+pointer capture) and when the capturing node unmounts; `ev.releasePointer()`
+ends it early. While captured, hover stays where it was — dragging must not
+light up every widget the pointer crosses.
+
+## Focus
+
+`focusable` opts a node into focus (`<textinput>` is focusable by
+default, and so is a scroll container with somewhere to scroll), `autoFocus`
+takes it at mount, and every drawn node has
+`focus()` / `blur()` / `focused` on its ref — plus `focusWithin`, which is
+true while focus is on the node **or inside it**, the question a modal asks
+before taking focus itself. To _draw_ that rather than read it, there is a
+`':focus-within'` style block
+([styling.md](styling.md#inline-pseudo-states)), which is what a row
+containing a field wants. `focus()` hands the node back, so a component
+can forward it straight out of an imperative handle. Focusing a node inside a
+scroll container scrolls it into view — unless a press focused it, since
+the node is under the pointer. Mousedown focuses the nearest
+focusable ancestor of the hit node; Tab / Shift+Tab cycle through focusable
+nodes in tree order. Keyboard
+events route to the focused node's ancestor chain. `disabled` opts a node
+back out of focus, whatever else it says.
+
+**A focused node shows a ring**, and how focus arrived decides whether it
+does. A press sets `:focus`; everything else — Tab, `autoFocus`,
+`node.focus()`, a modal handing focus back as it closes — also sets
+`:focus-visible`, and that is the state the ring is drawn on. A press on a
+**text control** is the one press that sets both, because a field the
+keyboard is about to go to has to say so however focus got there. It costs no
+layout and needs no opt-in; see
+[styling.md](styling.md#the-focus-ring) for restyling it.
+
+### Tab order
+
+`tabIndex` sets the sequential focus order, following the DOM's rules:
+
+- nodes with a **positive** `tabIndex` come first, in ascending order;
+- then everything focusable without one (the implicit `0` group), in tree
+  order;
+- `tabIndex={-1}` is focusable — by a press, and by `focus()` — but Tab
+  never lands on it;
+- an explicit `tabIndex` makes a node focusable without also passing
+  `focusable`.
+
+Tab out of a node that is not in the tab order (`tabIndex={-1}`, or a node
+outside the current focus scope) and traversal starts from the beginning of
+the order.
+
+```jsx
+<box tabIndex={1} />   {/* visited first  */}
+<box tabIndex={2} />   {/* then this      */}
+<box focusable />      {/* then tree order */}
+<box tabIndex={-1} />  {/* clickable, never tabbed to */}
+```
+
+Traversal is a **default action** like any other, and it runs last: an
+`onKeyDown` that calls `preventDefault()` on Tab keeps it, and so does an
+element whose own `defaultKeyDown` consumes it — an editor indenting with
+Tab. An element that does owes the keyboard user a way out of it, which is
+the Escape-arms-one-Tab convention in
+[extending.md](extending.md#behaviour-of-your-own).
+
+### Focus scopes (modals)
+
+`trapFocus` makes a node own a **focus scope**. While it is the innermost
+scope:
+
+- Tab / Shift+Tab only visit focusables inside it — the rest of the window
+  is unreachable by keyboard;
+- a press outside it does not move focus (poking at the window behind a
+  modal is inert as far as focus goes — the press itself still dispatches,
+  so pair it with `grab` + `onDismiss` for a real modal);
+- when the scope unmounts, focus goes back to whatever had it before the
+  scope opened — no bookkeeping in the widget.
+
+That is a modal dialog, with the popup taking focus at mount:
+
+```jsx
+function Dialog({ open, x, y, onClose }) {
+  if (!open) return null;
+  return (
+    <popup
+      trapFocus
+      grab
+      x={x}
+      y={y}
+      width={280}
+      height={120}
+      onDismiss={onClose}
+    >
+      <textinput autoFocus />
+      <Button label="OK" onPress={onClose} />
+    </popup>
+  );
+}
+```
+
+Scopes nest (a modal opened from a modal); the innermost one wins, and
+popping it hands focus back to the outer one. Programmatic `focus()` is
+never blocked by a scope — the trap is about Tab and presses.
+
+### Focus inside a `<popup>`
+
+An override-redirect window never receives the X input focus, so a popup
+cannot hold focus itself: the **owner window** does, and a node inside the
+popup can be the focused node of that window. Keys arrive at the owner
+window and are dispatched to it, then bubble out through the popup's
+position in the JSX tree into the owner's handlers, so nothing has to
+proxy them.
+
+One consequence worth knowing: a press inside a popup that lands on nothing
+focusable leaves the owner window's focus alone. Menus depend on it —
+their rows are not focusable, and the trigger keeps handling keys while the
+menu is open (`Menu`, `Select`).
+
+A popup with no owner window — a popover a tray click opened, in an app with
+no window of its own — has nowhere for its keys to arrive, and takes them
+itself with `grabKeyboard`
+([elements.md](elements.md#a-popover-under-a-tray-item)).
+
+### Window focus
+
+Node focus is per `<window>`, and the window itself may or may not be the
+one the X server sends keys to — that is the window manager's call.
+`<window onFocus>` / `<window onBlur>` report it (ntk ≥ 3.7.0, X
+`FocusIn`/`FocusOut`).
+
+While the window is unfocused the focused node **keeps** focus, exactly as
+`document.activeElement` survives a window blur in a browser — it just
+stops looking active: a `<textinput>` caret stops blinking, and resumes
+when the window is focused again. Calling `focus()` on a node in a window
+that does not have the input focus asks for it (X `SetInputFocus`), though
+a window manager is free to refuse.
+
+Which of an application's windows a key is _delivered_ to is a separate
+question again, and not one the application answers: the server sends it to
+the window holding the input focus, or to whichever descendant of that
+window the pointer happens to be over. A nested `<window>` and a `<popup>`
+put the two apart — the field is focused inside them, the keyboard belongs
+to the top-level — so a key is dispatched to **the node that has focus**,
+whichever of that top-level's windows it arrived at, and bubbles from there
+out through the JSX tree. Where more than one window holds a focused node,
+the one focused last is where the user is typing and the one that answers.
+
+"Unfocused" is likewise the **focus's** answer rather than any one window's.
+A `<popup>` shares its owner's focus, and a managed one — a `<Dialog>` — is a
+real window the window manager focuses in its own right, so opening one takes
+the X focus off the owner at the moment the field inside the dialog starts
+receiving keys. The caret follows the window that actually holds the
+keyboard, whichever of the ones sharing that focus it is; asking the owner
+alone is how a focused field ends up with a `:focus` ring and no caret. By
+the same token, `focus()` on a node inside an open dialog does not ask the
+server for the input focus — the dialog already has it.
+
+### Focus and visibility
+
+**Focus follows visibility.** A subtree that goes off the screen gives up
+the keyboard: a `<Suspense>` boundary showing its fallback, an `<Activity
+mode="hidden">`, a `display: 'none'`, a `<popup>` being unmapped. The
+focused node fires `onBlur`, `:focus`/`:focus-within` come off, and keys go
+to the window instead — because a control nobody can see must not be
+collecting keystrokes, and the application's state must not advance from
+them. Tab skips invisible nodes for the same reason.
+
+**And it comes back with it.** When the subtree is revealed, focus returns
+to where it was, ring and all, so a boundary that re-suspended mid-edit
+leaves the user typing where they were. Two rules keep that from being
+focus stealing:
+
+- it only happens when **nothing else has the keyboard** — anything focused
+  while the subtree was away keeps focus;
+- it is a restore rather than a navigation: no scrolling into view, and no
+  X `SetInputFocus`, so a background window revealing something never takes
+  the keyboard off another application.
+
+`createRoot({ restoreFocusOnReveal: false })` turns the second half off, for
+an app that wants the browser's answer — focus that fell to nothing stays
+there, and coming back is the user's own Tab. The release is not optional.
+
+## Cursors
+
+The `cursor` style property (`'pointer'`, `'text'`, `'wait'`, `'move'`,
+`'crosshair'`, `'ew-resize'`, `'ns-resize'`, `'grab'`, `'not-allowed'`, …)
+applies the deepest hovered node's cursor to the window, via ntk's cursor
+cache over the standard X cursor font.
+
+`cursor: 'none'` hides the pointer (ntk ≥ 4.2.0) — the kiosk case. It is
+the one name that is not a glyph in that font, so ntk builds it from an
+empty 1×1 mask. Note it is **not** the same as setting no cursor at all:
+with none of a node's ancestors naming one, the window inherits the root
+window's cursor and the pointer stays visible.
+
+## Drag and drop {#drag-and-drop}
+
+Drag and drop rides this event system — same hit testing, same
+capture/bubble dispatch, same style states — so the props sit alongside the
+pointer handlers on any drawn element, `<window>` or `<popup>`:
+
+```jsx
+<box
+  dropAccept={['files']}
+  onDrop={(e) => setPaths(e.files.map((f) => f.path))}
+  style={{ ':drag-over': { borderColor: '$accent' } }}
+/>
+```
+
+| handler                                | notes                                                                                   |
+| -------------------------------------- | --------------------------------------------------------------------------------------- |
+| `onDragEnter` / `onDragLeave`          | do not propagate — path diffing, like hover; paired with the `':drag-over'` state       |
+| `onDragOver`                           | per pointer position; `e.accept(action)` / `e.reject()` answer the source               |
+| `onDrop`                               | may be async — the protocol reply waits for the returned promise, bounded by a watchdog |
+| `onDragStart` / `onDrag` / `onDragEnd` | the source side of a `draggable` node; `':dragging'` styles it for the duration         |
+
+Two things that differ from the events above. A press on a `draggable` node
+is still a **click** until the pointer moves 4px, and a completed drag
+suppresses the click that would otherwise follow — the same bargain the DOM
+makes. And a drag that leaves the app's own windows keeps working: it is
+promoted to the platform's own protocol — XDND on X11, AppKit's dragging on
+Cocoa, the data device on Wayland, OLE on Windows — and can be dropped into
+a file manager, an editor or another react-x11 process, with the handlers
+unchanged.
+
+**The full reference is [drag-and-drop.md](drag-and-drop.md)**: the
+`dropAccept` matching rules, the event payload (`e.files`, `e.text`,
+`e.getData`, `e.items`), `dragData` and lazy payloads, the `useDropTarget`
+and `useDragSource` hooks, drag previews, interoperating with GTK and
+Firefox, and how to drive a drag in a test.