ntk 7.3.3 → 7.5.0

package/lib/app.js

@@ -93,6 +93,8 @@ export default class App {
     this._solidPictures = new Map();
     this._rasterizer = undefined;
     this._shm = undefined;
+    this._xinputPromise = null;
+    this._devicesPromise = null;
     // node-x11 emits X errors it cannot route to a request callback as
     // 'error' on the client — from inside its packet parser. With no
     // listener that emit throws and the parser never re-arms, silently
@@ -299,6 +301,53 @@ export default class App {
     });
   }
 
+  /**
+   * The XInput extension, or `null` where the server has none — asked once
+   * per connection.
+   *
+   * `ext.xi2` is `null` on a server that answers the extension query but
+   * speaks XI1 only, and every XI2 request needs it, so callers check both.
+   *
+   * @returns {Promise<object|null>}
+   */
+  xinput() {
+    if (!this._xinputPromise) {
+      this._xinputPromise = new Promise((resolve) => {
+        this.X.require('xinput', (err, ext) => resolve(err ? null : ext));
+      });
+    }
+    return this._xinputPromise;
+  }
+
+  /**
+   * Every input device the server knows about, from XI2's `XIQueryDevice`:
+   * `{deviceId, use, attachment, enabled, name, classes}`, the classes
+   * describing each device's keys, buttons, valuators and scroll axes (see
+   * node-x11's docs/ext/xinput.md). `[]` where there is no XI2.
+   *
+   * Cached, because it is what `Window.selectXI2` consults to find the
+   * scroll axes behind a wheel delta and it must not cost a round trip per
+   * event. The cache is dropped whenever a window with XI2 selected sees an
+   * `XIDeviceChanged` — a master pointer's axes are those of whichever slave
+   * moved last, so they change under it when the user picks up the mouse
+   * after using the touchpad.
+   *
+   * @param {{refresh?: boolean}} [options]
+   * @returns {Promise<object[]>}
+   */
+  inputDevices({ refresh = false } = {}) {
+    if (refresh) this._devicesPromise = null;
+    if (!this._devicesPromise) {
+      this._devicesPromise = this.xinput().then((XI) => {
+        if (!XI || !XI.xi2) return [];
+        return new Promise((resolve) => {
+          XI.XIQueryDevice(XI.AllDevices, (err, devices) => resolve(err ? [] : devices));
+        });
+      });
+    }
+    return this._devicesPromise;
+  }
+
   /** selection/clipboard transfer: write()/read() text (docs/clipboard.md) */
   get clipboard() {
     if (!this._clipboard) this._clipboard = new Clipboard(this);

package/lib/drawable.js

@@ -1,5 +1,10 @@
 import { EventEmitter } from 'node:events';
 
+// lib/ may not statically import node builtins (see docs/packaging.md); this
+// file is the one sanctioned exception for node:events, so it is also where
+// the rest of lib/ takes EventEmitter from.
+export { EventEmitter };
+
 export default class Drawable extends EventEmitter {
   getContext(name, ...args) {
     const factory = Drawable.renderingContextFactory[name];

package/lib/events_map.js

@@ -67,6 +67,10 @@ export const mask = {
   // not an X event of its own: Window derives it from the PropertyNotify for
   // _NET_WM_STATE, so it needs the same mask a 'property' listener does
   statechange: x11.eventMask.PropertyChange,
+  // also derived: a wheel is a click of button 4-7 in the core protocol, and
+  // a scroll valuator under XI2 (see lib/xi2.js). ButtonPress covers the core
+  // half; the XI2 half is opt-in per window and selects itself
+  wheel: x11.eventMask.ButtonPress,
   selection: 0,
   selection_request: 0,
   message: 0
@@ -81,7 +85,12 @@ export const mask = {
 export const coalesce = {
   mousemove: 'last',
   resize: 'last',
-  expose: 'union'
+  expose: 'union',
+  // 'accumulate' — scroll distance adds up. Keeping the last delta instead
+  // would throw away everything but the final step of a fast scroll, and a
+  // frame's worth of a touchpad's sub-notch deltas is exactly the case the
+  // smooth-scroll path exists for.
+  wheel: 'accumulate'
 };
 
 export const toSnake = {
@@ -90,6 +99,7 @@ export const toSnake = {
   onMouseOut: 'mouseout',
   onMouseDown: 'mousedown',
   onMouseUp: 'mouseup',
+  onWheel: 'wheel',
   onMap: 'map',
   onUnmap: 'unmap',
   onResize: 'resize',

package/lib/index.js

@@ -6,6 +6,16 @@ import { BLANK_CURSOR, CursorCache, cursorNames, cursorShapes, resolveCursorShap
 import { DEFAULT_GL_POLICY, GLError, GL_MODES, resolveGLPolicy, wantsDirect } from './gl.js';
 import { GLXError } from './glx.js';
 import Window from './window.js';
+import {
+  FocusProxy,
+  XEMBED,
+  XEMBED_OPCODE_NAMES,
+  XEmbedPlug,
+  XEmbedSocket,
+  decodeXEmbedInfo,
+  encodeXEmbedInfo,
+  readXEmbedInfo
+} from './xembed.js';
 import { loadLayout } from './yoga.js';
 import { decodeKey, groupForState } from './keyboard.js';
 import Pixmap from './pixmap.js';
@@ -210,6 +220,15 @@ export {
   App,
   Clipboard,
   Window,
+  // XEmbed (docs/xembed.md): also available as `ntk/xembed`
+  XEmbedSocket,
+  XEmbedPlug,
+  FocusProxy,
+  XEMBED,
+  XEMBED_OPCODE_NAMES,
+  encodeXEmbedInfo,
+  decodeXEmbedInfo,
+  readXEmbedInfo,
   BLANK_CURSOR,
   CursorCache,
   cursorNames,

package/lib/window.js

@@ -7,6 +7,17 @@ import { packIcons, unpackIcons } from './imagedata.js';
 import Pixmap from './pixmap.js';
 import * as xevents from './events_map.js';
 import { decodeKey } from './keyboard.js';
+import {
+  DEFAULT_XI2_EVENTS,
+  POINTER_EMULATED,
+  ScrollTracker,
+  WHEEL_BUTTONS,
+  normalizeXI2Types,
+  scrollAxes,
+  toNtkEvent,
+  wheelEvent,
+  xi2EventName
+} from './xi2.js';
 
 /**
  * How many rectangles a frame's dirty region is allowed to hold.
@@ -435,10 +446,16 @@ export default class Window extends Drawable {
     this._updateRegion = 0;
     this._presentSerial = 0;
     this._presentEid = 0;
+    // Generic Events (type 35) carry an extension opcode where a core event
+    // carries its code, so they are routed by opcode: Present's completions,
+    // XI2's device events, and whatever else selects them later.
+    this._geHandlers = new Map();
     // A direct GL context's swap chain, when one is presenting on this window
-    // (see _setGenericEventSink)
+    // — an override ahead of that table (see _setGenericEventSink)
     this._geSink = null;
     this._geSinkOpcode = 0;
+    // XI2 state, once a window has selected it (see selectXI2)
+    this._xi2 = null;
     // The vblank clock (see _onPresentComplete): the period learnt from
     // completion events, the samples it is drawn from, and the latch the
     // watchdog sets when completions stop arriving.
@@ -499,13 +516,15 @@ export default class Window extends Drawable {
       // window was asked to be, so the window manager's first ConfigureNotify
       // reports only what it actually overrode
       this._deliveredGeom = { x: this.x, y: this.y, width: this.width, height: this.height };
+      this.windowClass = args.windowClass ?? 0;
       const values = {
-        // NorthWest bit gravity: keep the old content anchored during
-        // resize instead of discarding it (less flicker between the resize
-        // and our redraw)
-        bitGravity: 1,
         eventMask: this.eventMask
       };
+      // NorthWest bit gravity: keep the old content anchored during resize
+      // instead of discarding it (less flicker between the resize and our
+      // redraw). An InputOnly window (class 2) has no content to anchor and
+      // the attribute is not one it accepts — setting it is a BadMatch.
+      if (this.windowClass !== 2) values.bitGravity = 1;
       for (const name of forwardedXAttributes) {
         if (args[name] !== undefined) values[name] = args[name];
       }
@@ -514,7 +533,6 @@ export default class Window extends Drawable {
       // parent of a different depth is a BadMatch (X11 CreateWindow)
       this.visual = args.visual ?? 0;
       this.depth = args.depth ?? 0;
-      this.windowClass = args.windowClass ?? 0;
       if (this.visual) {
         if (values.colormap === undefined) {
           this._ownedColormap = app.createColormap(this.visual);
@@ -591,6 +609,14 @@ export default class Window extends Drawable {
     if (args.alwaysOnTop) {
       this.setAlwaysOnTop(true);
     }
+    if (args.xi2) {
+      // fire and forget: until the extension answers, the window is on core
+      // events, which is where it would have been anyway. `await
+      // wnd.selectXI2()` is the form that says whether the server has XI2.
+      this.selectXI2(args.xi2 === true ? undefined : args.xi2).catch((err) =>
+        this.app.options.onXError?.(err)
+      );
+    }
     if (args.syncRequest && !args.id) {
       // fire and forget: the window manager only reads the counter when it
       // starts managing the window, and map() is the caller's next line at
@@ -612,19 +638,20 @@ export default class Window extends Drawable {
 
     X.event_consumers[this.id] = this;
     this.on('event', (ev) => {
-      // Present speaks in X Generic Events, which carry an extension opcode
-      // and a sub-type where a core event carries its code — the name table
-      // below cannot see them, and they are not events user code asked for
+      // Present and XI2 speak in X Generic Events, which carry an extension
+      // opcode and a sub-type where a core event carries its code — the name
+      // table below cannot see them, so they are routed by opcode instead
       if (ev.type === 35) {
         // A direct GL context presenting on this window selected these events
         // itself and owns the pixmaps they name, so they are its to read — and
         // it is the only user of Present there, a GL window having no backing
-        // store to blit.
+        // store to blit. Hence an override rather than another table entry:
+        // it claims the same extension the window's own blit path uses.
         if (this._geSink && ev.extension === this._geSinkOpcode) {
           this._geSink.handleEvent(ev);
-        } else if (this._presentExt && ev.extension === this._presentExt.majorOpcode) {
-          this._handlePresentEvent(ev);
+          return;
         }
+        this._geHandlers.get(ev.extension)?.(ev);
         return;
       }
       const ntkev = ev; // todo: clone
@@ -658,9 +685,12 @@ export default class Window extends Drawable {
           if (key.codepoint !== undefined) ev.codepoint = key.codepoint;
         }
       }
-      if (this._coalesce && xevents.coalesce[eventName]) {
-        this._enqueueCoalesced(eventName, ntkev);
-        return;
+      // a wheel is a button in the core protocol; say so in the units a
+      // consumer wants. Suppressed once XI2 is delivering the same scroll as
+      // valuators, which is the whole reason to select it (see selectXI2).
+      if (eventName === 'mousedown' && WHEEL_BUTTONS[ev.keycode] && !this._xi2?.smooth) {
+        const [deltaX, deltaY] = WHEEL_BUTTONS[ev.keycode];
+        this._deliverEvent('wheel', wheelEvent({ ...ntkev }, deltaX, deltaY, 'button'));
       }
       // the window manager reporting what it did with the window: a user who
       // hit maximize or a fullscreen hotkey changes the state behind the
@@ -672,19 +702,7 @@ export default class Window extends Drawable {
           () => {}
         );
       }
-      // deliver buffered state events before a discrete one so handlers see
-      // them in the order they happened (a drag sees the move, then the up)
-      this._flushCoalesced();
-      if (eventName === 'resize') this._tagResize(ntkev);
-      this.emit(eventName, ntkev);
-      // a WM_DELETE_WINDOW ClientMessage is the window manager *asking*, and
-      // 'close' is that question in a form an application can answer
-      if (eventName === 'message') {
-        this._emitCloseRequest(ntkev);
-        this._handleSyncRequest(ntkev);
-      }
-      // anything drawn during the handlers becomes visible in one blit
-      if (this._dirty) this._present();
+      this._deliverEvent(eventName, ntkev);
     });
 
     // Events about a *child* of this window: the substructure requests a
@@ -1168,6 +1186,32 @@ export default class Window extends Drawable {
     this._armTimer();
   }
 
+  /**
+   * Deliver one named event: buffer it if its kind coalesces, and otherwise
+   * flush what is buffered before emitting, so handlers see events in the
+   * order they happened (a drag sees the move, then the up).
+   *
+   * Every source ends here — the core event stream, the XI2 one, and the
+   * `wheel` both of them derive.
+   */
+  _deliverEvent(name, ev) {
+    if (this._coalesce && xevents.coalesce[name]) {
+      this._enqueueCoalesced(name, ev);
+      return;
+    }
+    this._flushCoalesced();
+    if (name === 'resize') this._tagResize(ev);
+    this.emit(name, ev);
+    // a WM_DELETE_WINDOW ClientMessage is the window manager *asking*, and
+    // 'close' is that question in a form an application can answer
+    if (name === 'message') {
+      this._emitCloseRequest(ev);
+      this._handleSyncRequest(ev);
+    }
+    // anything drawn during the handlers becomes visible in one blit
+    if (this._dirty) this._present();
+  }
+
   _enqueueCoalesced(name, ev) {
     const pending = this._frame.pending;
     const prev = pending.get(name);
@@ -1177,6 +1221,21 @@ export default class Window extends Drawable {
         ev.rects = [{ x: ev.x, y: ev.y, width: ev.width, height: ev.height }];
       }
       pending.set(name, ev);
+    } else if (xevents.coalesce[name] === 'accumulate') {
+      // scroll distance adds up, and the frame's scroll happened wherever the
+      // pointer ended up. The first event of the frame carries the sum, the
+      // way the union path grows its first event's rectangle.
+      prev.coalesced.push(ev);
+      prev.deltaX += ev.deltaX;
+      prev.deltaY += ev.deltaY;
+      prev.x = ev.x;
+      prev.y = ev.y;
+      prev.rootx = ev.rootx;
+      prev.rooty = ev.rooty;
+      prev.time = ev.time;
+      prev.buttons = ev.buttons;
+      prev.smooth = ev.smooth;
+      prev.source = ev.source;
     } else if (xevents.coalesce[name] === 'union') {
       prev.coalesced.push(ev);
       prev.rects.push({ x: ev.x, y: ev.y, width: ev.width, height: ev.height });
@@ -1284,6 +1343,163 @@ export default class Window extends Drawable {
     this._geSinkOpcode = sink ? majorOpcode : 0;
   }
 
+  /**
+   * Ask for XI2 device events on this window, and deliver them as the events
+   * ntk already has names for.
+   *
+   * What this buys is the wheel: the core protocol reports a scroll as a
+   * click of button 4/5/6/7, so a touchpad's two-finger gesture arrives as
+   * whole notches however finely the hardware measured it. XI2 carries the
+   * same gesture as a scroll *valuator*, and `wheel` then reports fractions
+   * of a notch (see docs/window.md "Wheel and smooth scrolling"). Touch and
+   * per-device input come with it — `ev.deviceId`/`ev.sourceId` are on every
+   * translated event, and the core protocol has no way to say either.
+   *
+   * Opt-in per window, via `createWindow({ xi2: true })` or this call,
+   * because selecting XI2 changes what the server sends: a window that has
+   * not asked keeps costing exactly what it did before.
+   *
+   * **Selecting XI2 replaces the core events of the same types.** The server
+   * delivers an event to a client once, and an XI2 selection wins, so
+   * `selectXI2(['Motion'])` means this window's `mousemove` is built from
+   * `XIMotion` from then on. It carries the same fields (plus `ev.xi2`,
+   * the device ids and sub-pixel `preciseX`/`preciseY`), so handlers do not
+   * change — but a window that selects XI2 KeyPress and nothing else still
+   * gets core motion, and mixing the two per-type is what the `types`
+   * argument is for.
+   *
+   * The emulated wheel buttons are dropped once the valuators are flowing:
+   * the server sends both halves of a smooth scroll (the axis and a button
+   * 4-7 click flagged `PointerEmulated`) so that clients which cannot read
+   * valuators still scroll, and delivering both would count every notch
+   * twice. So an app that opts in reads `wheel`, not `mousedown` on button 4.
+   *
+   * @param {string[]|string} [types] XI2 event type names —
+   *   `Motion`, `ButtonPress`, `ButtonRelease`, `KeyPress`, `KeyRelease`,
+   *   `TouchBegin`, `TouchUpdate`, `TouchEnd`. An empty array deselects.
+   * @param {{deviceId?: number}} [options] which device to select for,
+   *   defaulting to every master device (the virtual pointer and keyboard
+   *   the user is actually driving). A selection is per device, so a
+   *   selection on one device id does not replace one made on another.
+   * @returns {Promise<boolean>} false where the server has no XI2 — in which
+   *   case nothing changed and the window keeps its core events, `wheel`
+   *   included, at notch granularity
+   */
+  selectXI2(types = DEFAULT_XI2_EVENTS, { deviceId } = {}) {
+    const names = normalizeXI2Types(types);
+    return Promise.all([this.app.xinput(), this.app.inputDevices()]).then(([XI, devices]) => {
+      if (!XI || !XI.xi2 || this._destroyed) return false;
+      const target = deviceId ?? XI.AllMasterDevices;
+      if (!names.length) {
+        safeRelease(this.X, () => XI.XISelectEvents(this.id, { deviceId: target, mask: 0 }));
+        this._geHandlers.delete(XI.majorOpcode);
+        this._xi2 = null;
+        return true;
+      }
+      // DeviceChanged rides along uninvited: it is the only announcement that
+      // a master pointer's valuators are now some other slave's, which
+      // invalidates both the axis map and the accumulators built on it. Its
+      // body is undecoded, and the device id is all this needs from it.
+      safeRelease(this.X, () =>
+        XI.XISelectEvents(this.id, { deviceId: target, mask: [...names, 'DeviceChanged'] })
+      );
+      this._xi2 = {
+        ext: XI,
+        deviceId: target,
+        types: names,
+        // evtype -> the ntk event it becomes, resolved through the extension's
+        // own table rather than hardcoded numbers
+        byType: new Map(names.map((name) => [XI.EventType[name], xi2EventName[name]])),
+        scroll: this._xi2?.scroll ?? new ScrollTracker(),
+        axes: new Map(devices.map((device) => [device.deviceId, scrollAxes(device)])),
+        // whether the core wheel buttons are now redundant: a scroll-capable
+        // device plus a selection that carries its valuators
+        smooth: names.includes('Motion') && devices.some((device) => scrollAxes(device).size > 0)
+      };
+      this._geHandlers.set(XI.majorOpcode, (ev) => this._handleXI2Event(ev));
+      return true;
+    });
+  }
+
+  /**
+   * One XI2 Generic Event: scroll valuators become `wheel`, everything else
+   * becomes the core-shaped event it stands in for.
+   */
+  _handleXI2Event(ev) {
+    const xi2 = this._xi2;
+    if (!xi2) return;
+    if (ev.evtype === xi2.ext.EventType.DeviceChanged) {
+      this._refreshXI2Devices(ev.deviceId);
+      return;
+    }
+    const name = xi2.byType.get(ev.evtype);
+    if (!name) return;
+
+    const base = toNtkEvent(name, ev);
+    base.window = this;
+    base.target = this;
+
+    if (name === 'mousemove') {
+      // a scroll is a Motion carrying scroll axes; the pointer itself did not
+      // move, so it is a wheel event and not also a mouse move — including
+      // the first one, which has nothing to subtract from yet
+      const scroll = xi2.scroll.delta(ev, this._xi2Axes(ev));
+      if (scroll) {
+        if (scroll.moved) {
+          this._deliverEvent('wheel', wheelEvent(base, scroll.deltaX, scroll.deltaY, 'valuator'));
+        }
+        return;
+      }
+    }
+    if (name === 'mousedown' || name === 'mouseup') {
+      const wheelButton = WHEEL_BUTTONS[ev.detail];
+      // the click the server emulated for clients that cannot read valuators
+      // — we can, and the valuator half of the same scroll is already on its
+      // way, so this one is noise
+      if (wheelButton && ev.flags & POINTER_EMULATED) return;
+      if (wheelButton && name === 'mousedown') {
+        const wheel = wheelEvent({ ...base }, wheelButton[0], wheelButton[1], 'button');
+        this._deliverEvent('wheel', wheel);
+      }
+    }
+    if (name === 'keydown' || name === 'keyup') {
+      const key = decodeKey(this.X.keycode2keysyms[ev.detail], base.buttons);
+      if (key) {
+        base.keysym = key.keysym;
+        base.baseKeysym = key.baseKeysym;
+        base.group = key.group;
+        if (key.codepoint !== undefined) base.codepoint = key.codepoint;
+      }
+    }
+    this._deliverEvent(name, base);
+  }
+
+  /** This window's scroll-axis map for the device an event came from. */
+  _xi2Axes(ev) {
+    return this._xi2?.axes.get(ev.deviceId);
+  }
+
+  /**
+   * A master device's slave changed: re-read what its axes are now, and drop
+   * the accumulators, because the values arriving next belong to a different
+   * device and subtracting across the switch is the jump seeding exists to
+   * avoid.
+   */
+  _refreshXI2Devices(deviceId) {
+    const xi2 = this._xi2;
+    if (!xi2) return;
+    xi2.scroll.reset(deviceId);
+    this.app.inputDevices({ refresh: true }).then(
+      (devices) => {
+        if (this._xi2 !== xi2) return; // deselected or reselected meanwhile
+        xi2.axes = new Map(devices.map((device) => [device.deviceId, scrollAxes(device)]));
+        xi2.smooth =
+          xi2.types.includes('Motion') && devices.some((device) => scrollAxes(device).size > 0);
+      },
+      () => {}
+    );
+  }
+
   /**
    * Present's events, which are the ones the core event table cannot name:
    * they arrive as X Generic Events (type 35), carrying an extension opcode
@@ -1702,6 +1918,7 @@ export default class Window extends Drawable {
       safeRelease(X, () => fixes.CreateRegion(this._updateRegion, []));
       this._presentExt = present;
       this._fixesExt = fixes;
+      this._geHandlers.set(present.majorOpcode, (ev) => this._handlePresentEvent(ev));
       this._selectPresentInput();
       return this;
     });
@@ -2612,16 +2829,21 @@ export default class Window extends Drawable {
 
     if (mapped) {
       const root = this.app.display.screen[0].root;
-      const messageType = await this.atom('_NET_WM_STATE');
-      if (this._destroyed) return false;
-      safeRelease(this.X, () => {
-        this.X.SendClientMessage(root, this.id, messageType, 32, [
+      // EWMH 7.7: delivered to the root with the substructure mask, so the
+      // window manager watching there sees it, but about this window
+      await this.sendClientMessage(
+        '_NET_WM_STATE',
+        [
           mode,
           ids[0],
           ids[1] ?? 0,
           1 // source indication: a normal application, not a pager
-        ]);
-      });
+        ],
+        {
+          target: root,
+          mask: x11.eventMask.SubstructureRedirect | x11.eventMask.SubstructureNotify
+        }
+      );
     } else {
       await this._writeWmState(ids, mode);
     }
@@ -3168,6 +3390,58 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Send a ClientMessage about this window (X SendEvent with a
+   * ClientMessage payload).
+   *
+   * ClientMessage is the carrier of every convention layered over the core
+   * protocol — EWMH state changes, WM_PROTOCOLS, XEmbed, XDND, the system
+   * tray — and they differ only in the atom naming the message and the five
+   * 32-bit words in it. `type` is an atom name (or an already-interned id),
+   * `data` the words; anything past the end of the list is sent as zero.
+   *
+   *   await wnd.sendClientMessage('WM_PROTOCOLS', [deleteAtom, time]);
+   *
+   * Two options carry the meaning that the raw request buries in argument
+   * order:
+   *
+   * - `target` — where the message is *delivered*, which is not always the
+   *   window it is *about*. EWMH messages are about a client window and
+   *   delivered to the root, so the window manager (which selected
+   *   SubstructureRedirect there) sees them.
+   * - `mask` — who on the target gets it. `0`, the default, delivers to the
+   *   client that owns the target window whatever it selected, which is
+   *   what a message addressed to another client needs. Root-window EWMH
+   *   messages instead pass
+   *   `SubstructureRedirect | SubstructureNotify`.
+   *
+   * @param {string|number} type atom name of the message type, or its id
+   * @param {number[]} [data] up to five 32-bit words (ten at format 16,
+   *   twenty at format 8)
+   * @param {object} [options] `{ target = this.id, format = 32, mask = 0 }`
+   * @returns {Promise<Window>}
+   */
+  async sendClientMessage(type, data = [], options = {}) {
+    const { target = this.id, format = 32, mask = 0 } = options;
+    const slots = { 8: 20, 16: 10, 32: 5 }[format];
+    if (!slots) {
+      throw new TypeError(`sendClientMessage: format must be 8, 16 or 32, got ${format}`);
+    }
+    if (data.length > slots) {
+      // the wire event is 32 bytes and no more; sending the first `slots`
+      // words of a longer list would drop the rest without a sound
+      throw new RangeError(
+        `sendClientMessage: a format-${format} ClientMessage carries ${slots} values, got ${data.length}`
+      );
+    }
+    const messageType = typeof type === 'number' ? type : await this.atom(type);
+    if (this._destroyed) return this;
+    safeRelease(this.X, () => {
+      this.X.SendClientMessage(target, this.id, messageType, format, data, mask);
+    });
+    return this;
+  }
+
   /**
    * Ask the client to close, the polite way: a WM_DELETE_WINDOW client
    * message if it advertised the protocol in WM_PROTOCOLS, so it can save
@@ -3187,13 +3461,11 @@ export default class Window extends Drawable {
       safeRelease(this.X, () => this.X.KillClient(this.id));
       return false;
     }
-    const wmProtocols = await this.atom('WM_PROTOCOLS');
-    // mask 0: deliver to the client that created the window, not to whoever
-    // selected events on it — a WM_PROTOCOLS message is addressed to the
-    // owner, so it must not go out with the EWMH substructure default
-    safeRelease(this.X, () =>
-      this.X.SendClientMessage(this.id, this.id, wmProtocols, 32, [deleteAtom, 0 /* CurrentTime */], 0)
-    );
+    // the default mask of 0 delivers to the client that created the window,
+    // not to whoever selected events on it — a WM_PROTOCOLS message is
+    // addressed to the owner, so it must not go out with the EWMH
+    // substructure mask
+    await this.sendClientMessage('WM_PROTOCOLS', [deleteAtom, 0 /* CurrentTime */]);
     return true;
   }