ntk 8.3.1 → 8.4.1

package/README.md

@@ -122,9 +122,16 @@ Server-side resources support `using` / `await using` (Node 24+):
 
 ## 3d graphics
 
-Only indirect GLX is supported, with most of the OpenGL 1.4 api implemented.
-Note that on many systems indirect GLX is disabled by default —
-[you'll need to enable it for gl to work](https://github.com/sidorares/node-x11/issues/117#issuecomment-214762185).
+Two backends, chosen by `glPolicy`
+([docs/context-gles.md](docs/context-gles.md)):
+
+- **direct** (opt-in) — shader GL on the real GPU with no pixels on the
+  socket: OpenGL ES 2 over DRI3 + Present on Linux, CGL over the Apple-DRI
+  extension on macOS/XQuartz. Needs the optional `x11-dri` addon.
+- **indirect GLX** (default) — most of the OpenGL 1.4 api, serialized into
+  the X connection. Note that on many systems indirect GLX is disabled by
+  default —
+  [you'll need to enable it for gl to work](https://github.com/sidorares/node-x11/issues/117#issuecomment-214762185).
 
 ```js
 import { createClient } from 'ntk';

package/lib/app.js

@@ -1,7 +1,7 @@
 import { connectionGone } from './cleanup.js';
 import Clipboard from './clipboard.js';
 import { CursorCache } from './cursor.js';
-import { GLError, backendFor, glCapabilities, glError, resolveGLPolicy } from './gl.js';
+import { GLError, backendFor, glCapabilities, glError, nativeRefreshRate, resolveGLPolicy } from './gl.js';
 import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
 import Pixmap from './pixmap.js';
@@ -254,6 +254,19 @@ export default class App {
   _probeRefreshRate() {
     this._refreshProbe = null; // in progress; only ever started once
     const X = this.X;
+    // RandR's answer, or the native layer's where RandR has no usable one.
+    // An implausible rate is treated as no answer, not clamped: XQuartz
+    // synthesizes real timing for its canned mode list but fills the current
+    // desktop-sized mode with dot_clock = width * height — exactly 1 Hz — so
+    // the number that describes what is actually driving the panel has to
+    // come from the OS (x11-dri >= 0.6.0, apple.refreshRate()).
+    const plausible = (rate) => rate >= MIN_REFRESH_RATE && rate <= MAX_REFRESH_RATE;
+    const settle = (rate) => {
+      if (!plausible(rate)) rate = nativeRefreshRate();
+      if (!rate || !plausible(rate)) return;
+      this._refreshRate = rate;
+      this._adoptFrameInterval(1000 / rate);
+    };
     // A connection on its way out is one more "no rate to be had". The probe
     // is started lazily by the first window built on this connection, which
     // may be one adopted from an event still arriving as it closes — and
@@ -261,10 +274,10 @@ export default class App {
     // event dispatch has no caller to catch it (issue #321).
     if (connectionGone(X)) return;
     X.require('randr', (err, R) => {
-      if (err || !R) return;
+      if (err || !R) return settle(0);
       const root = this.display.screen[0].root;
       R.GetScreenResourcesCurrent(root, (resourcesError, resources) => {
-        if (resourcesError || !resources?.crtcs?.length) return;
+        if (resourcesError || !resources?.crtcs?.length) return settle(0);
         const modes = new Map(resources.modeinfos.map((mode) => [mode.id, mode]));
         let pending = resources.crtcs.length;
         let best = 0;
@@ -273,9 +286,7 @@ export default class App {
             // a crtc with no mode is one that is switched off
             if (!crtcError && info) best = Math.max(best, modeRate(modes.get(info.mode)));
             if (--pending) return;
-            if (best < MIN_REFRESH_RATE || best > MAX_REFRESH_RATE) return;
-            this._refreshRate = best;
-            this._adoptFrameInterval(1000 / best);
+            settle(best);
           });
         }
       });
@@ -603,11 +614,11 @@ export default class App {
    * `createWindow` and the whole object to `wnd.getContext('opengl', config)`.
    *
    * The spec is GLX's attribute vocabulary either way, because a caller
-   * should not have to write the request twice: `DEPTH_SIZE` becomes the EGL
-   * depth-buffer size on the direct backend, and `ALPHA_SIZE` picks an ARGB
-   * visual there rather than an fbconfig with an alpha channel. Direct needs
-   * no round trip to answer — there are no fbconfigs in it, only a window the
-   * GPU's buffers can be copied or flipped into.
+   * should not have to write the request twice: `DEPTH_SIZE` becomes the
+   * depth-buffer size of the direct backend's context (EGL on Linux, CGL on
+   * macOS), and `ALPHA_SIZE` picks an ARGB visual there rather than an
+   * fbconfig with an alpha channel. Direct needs no round trip to answer —
+   * there are no fbconfigs in it, only a window the GPU draws for.
    *
    * @param {object} [spec] GLX attributes, e.g. `{ DEPTH_SIZE: 24 }`
    */
@@ -629,6 +640,8 @@ export default class App {
     }
     return {
       backend: 'direct',
+      // which direct pipeline this connection runs: 'dri3' or 'appledri'
+      flavor: caps.flavor,
       // depth 24 on the root visual needs no colormap of its own, which is
       // why an opaque GL window here is an ordinary window
       visual: argb?.visual ?? screen.root_visual,

package/lib/appledri.js

@@ -0,0 +1,177 @@
+// Apple-DRI: XQuartz's direct-rendering extension — the macOS counterpart of
+// DRI3. Where DRI3 passes dma-buf descriptors from client to server,
+// Apple-DRI runs the other way: the *server* owns a WindowServer surface for
+// the drawable and exports it to the client's WindowServer connection,
+// identified by (client_id, key[2]). What the client does with the key —
+// import it and attach an OpenGL context through the Xplugin/CGL system
+// libraries — is native-code territory: the x11-dri addon's `apple`
+// namespace (lib/renderingcontext_cgl.js is the consumer).
+//
+// The protocol half lives here rather than in node-x11 because node-x11 does
+// not ship it yet; the binding is written in node-x11's lib/ext style so it
+// can move there verbatim when it does (docs/context-gles.md#macos).
+//
+// Protocol source (there is no shipped header — the extension is defined in
+// the XQuartz server tree):
+//   https://github.com/XQuartz/xorg-server/blob/master/hw/xquartz/xpr/appledristr.h
+//   https://github.com/XQuartz/xorg-server/blob/master/hw/xquartz/xpr/appledri.h
+
+/*
+#define X_AppleDRIQueryVersion                0
+#define X_AppleDRIQueryDirectRenderingCapable 1
+#define X_AppleDRICreateSurface               2
+#define X_AppleDRIDestroySurface              3
+(4..8: AuthConnection and the shm pixmap requests — the accelerated path
+needs none of them, so they are not bound)
+*/
+
+/** Sub-codes of the AppleDRISurfaceNotify event's `kind`. */
+export const NotifyKind = {
+  /** the window moved or resized under the surface: `ctx.update()` */
+  Changed: 0,
+  /** the surface is gone (window unmapped, frame recreated): CreateSurface + attach anew */
+  Destroyed: 1
+};
+
+/**
+ * Bind the Apple-DRI extension on a node-x11 display.
+ *
+ * Resolves the extension object — with the requests, `events`, `NotifyKind`
+ * and `errors` below on it — or `null` where the server has no Apple-DRI,
+ * which is every server that is not XQuartz. Asked once per connection and
+ * cached; the event and error parsers are registered on first resolution.
+ *
+ * The requests are callback-style, like every node-x11 extension:
+ *
+ * - `QueryVersion(cb)` -> `{ major, minor, patch }`
+ * - `QueryDirectRenderingCapable(screen, cb)` -> `boolean`
+ * - `CreateSurface(screen, drawable, clientId, cb)` -> `{ key: [k0, k1], uid }`
+ * - `DestroySurface(screen, drawable)` (void)
+ *
+ * `CreateSurface` makes the server create (or reference) a WindowServer
+ * surface for the drawable and export it to the process whose WindowServer
+ * id is `clientId` (x11-dri: `dri.apple.clientId()`). `key` is what
+ * `AppleContext.attach()` consumes; `uid` is the server-side surface id that
+ * SurfaceNotify events carry as `arg` — route by uid, not by window id.
+ *
+ * The `AppleDRISurfaceNotify` event is *classic* (type `firstEvent + 3`),
+ * not a GenericEvent, and is sent unsolicited to the client that created the
+ * surface — there is no event mask to select. It reaches node-x11's
+ * client-level `'event'` stream only (no `wid` field for per-window
+ * routing), parsed as `{ name: 'AppleDRISurfaceNotify', kind, time, arg }`.
+ *
+ * @param {object} display node-x11 display
+ * @returns {Promise<object|null>}
+ */
+export function requireAppleDRI(display) {
+  const X = display.client;
+  if (X._appleDRIPromise) return X._appleDRIPromise;
+  X._appleDRIPromise = new Promise((resolve) => {
+    X.QueryExtension('Apple-DRI', (err, ext) => {
+      if (err || !ext.present) return resolve(null);
+
+      // -> { major, minor, patch }
+      ext.QueryVersion = (cb) => {
+        X.seq_num++;
+        const b = Buffer.alloc(4);
+        b.writeUInt8(ext.majorOpcode, 0);
+        b.writeUInt8(0, 1);
+        b.writeUInt16LE(1, 2);
+        X.pack_stream.put(b);
+        X.replies[X.seq_num] = [
+          (buf) => ({
+            major: buf.readUInt16LE(0),
+            minor: buf.readUInt16LE(2),
+            patch: buf.readUInt32LE(4)
+          }),
+          cb
+        ];
+        X.pack_stream.submit(true);
+      };
+
+      // -> boolean
+      ext.QueryDirectRenderingCapable = (screen, cb) => {
+        X.seq_num++;
+        const b = Buffer.alloc(8);
+        b.writeUInt8(ext.majorOpcode, 0);
+        b.writeUInt8(1, 1);
+        b.writeUInt16LE(2, 2);
+        b.writeUInt32LE(screen >>> 0, 4);
+        X.pack_stream.put(b);
+        X.replies[X.seq_num] = [(buf) => buf.readUInt8(0) !== 0, cb];
+        X.pack_stream.submit(true);
+      };
+
+      // -> { key: [key0, key1], uid }
+      ext.CreateSurface = (screen, drawable, clientId, cb) => {
+        X.seq_num++;
+        const b = Buffer.alloc(16);
+        b.writeUInt8(ext.majorOpcode, 0);
+        b.writeUInt8(2, 1);
+        b.writeUInt16LE(4, 2);
+        b.writeUInt32LE(screen >>> 0, 4);
+        b.writeUInt32LE(drawable >>> 0, 8);
+        b.writeUInt32LE(clientId >>> 0, 12);
+        X.pack_stream.put(b);
+        X.replies[X.seq_num] = [
+          (buf) => ({
+            key: [buf.readUInt32LE(0), buf.readUInt32LE(4)],
+            uid: buf.readUInt32LE(8)
+          }),
+          cb
+        ];
+        X.pack_stream.submit(true);
+      };
+
+      ext.DestroySurface = (screen, drawable) => {
+        X.seq_num++;
+        const b = Buffer.alloc(12);
+        b.writeUInt8(ext.majorOpcode, 0);
+        b.writeUInt8(3, 1);
+        b.writeUInt16LE(3, 2);
+        b.writeUInt32LE(screen >>> 0, 4);
+        b.writeUInt32LE(drawable >>> 0, 8);
+        X.pack_stream.put(b);
+        X.pack_stream.submit(false);
+      };
+
+      ext.events = {
+        AppleDRISurfaceNotify: 3 // 0..2 are obsolete
+      };
+      ext.NotifyKind = NotifyKind;
+
+      X.eventParsers[ext.firstEvent + ext.events.AppleDRISurfaceNotify] = (
+        type,
+        seq,
+        extra,
+        code,
+        raw
+      ) => ({
+        type,
+        seq,
+        name: 'AppleDRISurfaceNotify',
+        kind: code, // NotifyKind
+        time: extra,
+        arg: raw.readUInt32LE(4) // the surface uid, NOT a window id
+      });
+
+      ext.errors = {
+        ClientNotLocal: 0,
+        OperationNotSupported: 1
+      };
+      // node-x11 names an extension error it cannot decode after a core one;
+      // give both of Apple-DRI's a message that says what to do instead
+      X.errorParsers[ext.firstError + ext.errors.ClientNotLocal] = (error) => {
+        error.message =
+          'Apple-DRI: the client is not local — surfaces can only be exported to a process on the same machine as the X server';
+      };
+      X.errorParsers[ext.firstError + ext.errors.OperationNotSupported] = (error) => {
+        error.message =
+          'Apple-DRI: operation not supported — the server refused the request for this drawable (a root or already-destroyed window, or a server running without the Xplugin backend)';
+      };
+
+      resolve(ext);
+    });
+  });
+  return X._appleDRIPromise;
+}

package/lib/gl.js

@@ -7,11 +7,17 @@
 //    into the X connection. Reaches any server that allows indirect contexts,
 //    including over a network, and is a fixed-function OpenGL 1.x pipeline
 //    with no shaders, because that is what the GLX protocol encodes.
-//  - **direct** (lib/renderingcontext_gles.js) — a GPU render node draws the
-//    frame, and the finished buffer reaches the server as a dma-buf
-//    descriptor over DRI3 + Present. OpenGL ES 2 with real shaders, and no
-//    pixels on the socket; local connections only, and it needs the optional
-//    `x11-dri` addon.
+//  - **direct** — the GPU draws the frame and no pixels cross the socket;
+//    real shaders; local connections only; needs the optional `x11-dri`
+//    addon. It comes in two *flavors*, one per platform, behind the same
+//    context contract:
+//      - `dri3` (Linux, lib/renderingcontext_gles.js): OpenGL ES 2 on a DRM
+//        render node, finished buffers handed to the server as dma-buf
+//        descriptors over DRI3 + Present.
+//      - `appledri` (macOS/XQuartz, lib/renderingcontext_cgl.js): the server
+//        exports the window's WindowServer surface over the Apple-DRI
+//        extension, and a CGL context draws straight into it — desktop GL
+//        with ES2 compatibility, so the same shaders compile.
 //
 // Which one runs is `glPolicy`, and the default is `indirect` — the backend
 // that has always run. See docs/context-gles.md.
@@ -20,6 +26,7 @@
 // caller asked for, and what that resolves to. Neither context imports the
 // other, and the direct one is only ever loaded when the answer is `direct`.
 
+import { requireAppleDRI } from './appledri.js';
 import { nodeRequire } from './builtin.js';
 
 /**
@@ -29,18 +36,28 @@ import { nodeRequire } from './builtin.js';
  * - `GL_DISABLED` — `glPolicy: 'off'`; nothing tried.
  * - `GL_NO_ADDON` — the optional `x11-dri` addon is not installed or would
  *   not load. `npm install x11-dri`.
- * - `GL_NO_DRIVER` — the addon loaded but the GPU libraries it needs are
- *   missing (`libgbm`, `libEGL`, `libGLESv2`), or this is not Linux.
- * - `GL_NO_DEVICE` — no readable DRM render node (`/dev/dri/renderD*`).
- * - `GL_REMOTE_DISPLAY` — a TCP or forwarded display, so there is no local
- *   socket to hand the server a buffer down.
+ * - `GL_NO_DRIVER` — the addon loaded but the platform libraries it needs
+ *   are missing: `libgbm`/`libEGL`/`libGLESv2` on Linux,
+ *   libXplugin/OpenGL.framework on macOS — or the platform has no direct
+ *   path at all.
+ * - `GL_NO_DEVICE` — no readable DRM render node (`/dev/dri/renderD*`);
+ *   Linux only, macOS needs no device node.
+ * - `GL_REMOTE_DISPLAY` — a TCP or forwarded display; both flavors are
+ *   local-only by construction.
  * - `GL_NO_FD_PASSING` — the display is local, but this JavaScript runtime
  *   cannot send a descriptor over the socket. Bun is the case in the field;
- *   x11 does it through a Node internal Bun does not implement.
- * - `GL_NO_DRI3` — the server has no DRI3/Present (Xvfb, Xephyr, XQuartz).
+ *   x11 does it through a Node internal Bun does not implement. Linux only —
+ *   Apple-DRI passes no descriptors.
+ * - `GL_NO_DRI3` — the server has no DRI3/Present (Xvfb, Xephyr, XQuartz —
+ *   though XQuartz has its own path, see `GL_NO_APPLEDRI`).
+ * - `GL_NO_APPLEDRI` — macOS, and the server has no Apple-DRI extension:
+ *   not XQuartz, or an XQuartz running without its Xplugin backend.
+ * - `GL_NO_WINDOWSERVER` — macOS, but this process has no WindowServer
+ *   session to import surfaces into — an SSH session. Run from the
+ *   logged-in GUI session.
  * - `GL_IMPORT_FAILED` — the server refused the buffer; usually client and
  *   server on different DRM devices.
- * - `GL_CONTEXT_FAILED` — GBM/EGL setup failed for some other reason.
+ * - `GL_CONTEXT_FAILED` — GPU context setup failed for some other reason.
  */
 export const GLError = {
   DISABLED: 'GL_DISABLED',
@@ -50,6 +67,8 @@ export const GLError = {
   REMOTE_DISPLAY: 'GL_REMOTE_DISPLAY',
   NO_FD_PASSING: 'GL_NO_FD_PASSING',
   NO_DRI3: 'GL_NO_DRI3',
+  NO_APPLEDRI: 'GL_NO_APPLEDRI',
+  NO_WINDOWSERVER: 'GL_NO_WINDOWSERVER',
   IMPORT_FAILED: 'GL_IMPORT_FAILED',
   CONTEXT_FAILED: 'GL_CONTEXT_FAILED'
 };
@@ -152,6 +171,22 @@ export function setDriAddon(module) {
   addon = module;
 }
 
+/**
+ * The display's refresh rate asked of the native layer, in Hz, for servers
+ * whose RandR carries no usable timing — XQuartz reports the current
+ * desktop-sized mode with dot_clock = width * height, exactly 1 Hz.
+ * `null` everywhere there is no answer: not darwin, no addon (or one
+ * predating 0.6.0), or a session with no display to ask.
+ */
+export function nativeRefreshRate() {
+  if (globalThis.process?.platform !== 'darwin') return null;
+  try {
+    return loadDriAddon()?.apple?.refreshRate?.() ?? null;
+  } catch {
+    return null;
+  }
+}
+
 const INSTALL_HINT = `Direct rendering needs the optional native addon:
 
   npm install x11-dri
@@ -161,11 +196,18 @@ tools are needed; anything else compiles with node-gyp and a C toolchain. ntk
 does not depend on it — without it, GL runs through indirect GLX.`;
 
 /**
- * What the *client side* can do, before any server is asked: the addon, the
- * GPU libraries under it, and a render node to draw on. Never throws.
+ * What the *client side* can do, before any server is asked: the addon and
+ * the platform libraries under it — plus, on Linux, a render node to draw
+ * on. Never throws.
+ *
+ * `flavor` on an ok answer says which direct pipeline this machine runs:
+ * `'dri3'` (Linux — GBM/EGL, dma-buf to the server) or `'appledri'`
+ * (macOS — Apple-DRI surface export, CGL). macOS needs no device scan; the
+ * window's surface is the render target, so `device` is `null` there.
  *
  * @returns {{ok: boolean, code?: string, message?: string, hint?: string,
- *   device?: string, devices?: string[], probe?: object}}
+ *   flavor?: 'dri3'|'appledri', device?: string|null, devices?: string[],
+ *   probe?: object}}
  */
 export function probeDirect(policy = DEFAULT_GL_POLICY) {
   const dri = loadDriAddon();
@@ -185,6 +227,28 @@ export function probeDirect(policy = DEFAULT_GL_POLICY) {
     return { ok: false, code: GLError.NO_DRIVER, message: `x11-dri probe() failed: ${err.message}` };
   }
 
+  if (probe.platform === 'darwin') {
+    // The macOS path draws through Apple-DRI + CGL, not GBM/EGL — probe()
+    // reports it as `appledri`: `true`, or the string saying why not. An
+    // addon from before 0.5.0 has no such key at all.
+    if (probe.appledri !== true) {
+      return {
+        ok: false,
+        code: GLError.NO_DRIVER,
+        message: `the libraries direct rendering needs on macOS are unavailable (appledri: ${
+          probe.appledri ?? 'not reported — this x11-dri predates Apple-DRI support'
+        })`,
+        hint:
+          probe.appledri === undefined
+            ? 'Upgrade the addon: npm install x11-dri@latest (Apple-DRI support arrived in 0.5.0).'
+            : 'The macOS path needs XQuartz installed (it dlopen()s libXplugin from /opt/X11)\nand the system OpenGL framework — https://www.xquartz.org.',
+        probe
+      };
+    }
+    // no render nodes on macOS: the window's own surface is the target
+    return { ok: true, flavor: 'appledri', device: null, devices: [], probe };
+  }
+
   // probe() reports each capability as `true` or as the string saying why not
   const missing = ['gbm', 'egl', 'gles'].filter((key) => probe[key] !== true);
   if (missing.length) {
@@ -195,7 +259,7 @@ export function probeDirect(policy = DEFAULT_GL_POLICY) {
       message: `the GPU libraries direct rendering needs are unavailable (${detail})`,
       hint:
         probe.platform && probe.platform !== 'linux'
-          ? `Direct rendering is Linux-only — dma-buf, GBM and DRI3 have no equivalent on ${probe.platform}.`
+          ? `Direct rendering needs Linux (DRI3/dma-buf) or macOS (Apple-DRI/XQuartz) — ${probe.platform} has neither path.`
           : 'Install Mesa (libgbm1, libegl1, libgles2 on Debian/Ubuntu). They are dlopen()ed at\nrun time, so no rebuild of x11-dri is needed once they are there.',
       probe
     };
@@ -219,7 +283,7 @@ export function probeDirect(policy = DEFAULT_GL_POLICY) {
       devices
     };
   }
-  return { ok: true, device, devices, probe };
+  return { ok: true, flavor: 'dri3', device, devices, probe };
 }
 
 // ---------------------------------------------------------------------------
@@ -253,13 +317,20 @@ const requireExt = (X, name) =>
 /**
  * Everything about `app` that decides the backend, answered once and cached.
  *
- * The two extension queries are the only round trips, and they only happen
+ * The extension queries are the only round trips, and they only happen
  * under a policy that could use direct — `createClient` warms this during the
  * connect handshake for exactly that reason, so `getContext` can decide
  * synchronously afterwards.
  *
- * @returns {Promise<{direct: boolean, indirect: boolean, device: string|null,
- *   reason: Error|null, DRI3: object|null, Present: object|null}>}
+ * `flavor` names the direct pipeline where `direct` is true: `'dri3'`
+ * carries `DRI3` and `Present`, `'appledri'` carries `AppleDRI` (the
+ * lib/appledri.js extension object) and `appleClientId` (this process's
+ * WindowServer id, which CreateSurface exports surfaces to).
+ *
+ * @returns {Promise<{direct: boolean, indirect: boolean,
+ *   flavor: 'dri3'|'appledri'|null, device: string|null, reason: Error|null,
+ *   DRI3: object|null, Present: object|null, AppleDRI: object|null,
+ *   appleClientId: number|null}>}
  */
 export function glCapabilities(app) {
   if (app._glCaps) return app._glCaps;
@@ -269,10 +340,13 @@ export function glCapabilities(app) {
     const fail = (code, message, hint) => ({
       direct: false,
       indirect,
+      flavor: null,
       device: null,
       reason: glError(code, message, hint),
       DRI3: null,
-      Present: null
+      Present: null,
+      AppleDRI: null,
+      appleClientId: null
     });
 
     if (policy.mode === 'off') {
@@ -281,11 +355,67 @@ export function glCapabilities(app) {
     if (!app.display.isLocalSocket) {
       return fail(
         GLError.REMOTE_DISPLAY,
-        'this X connection is not a local socket, and DRI3 works by passing a descriptor down one',
-        'Direct rendering is local-only by construction. Over a network, indirect GLX is\n' +
-          'the backend that can work at all — leave glPolicy at its default.'
+        'this X connection is not a local socket, and direct rendering is same-machine by construction (DRI3 passes a descriptor down the socket; Apple-DRI exports a surface to a local process)',
+        'Over a network, indirect GLX is the backend that can work at all — leave\n' +
+          'glPolicy at its default.'
       );
     }
+
+    const client = probeDirect(policy);
+    if (!client.ok) return fail(client.code, client.message, client.hint);
+
+    if (client.flavor === 'appledri') {
+      // No descriptor ever crosses this socket — the fd-passing checks the
+      // dri3 flavor needs below do not apply, which is also what lets this
+      // path work under runtimes that cannot send one.
+      const dri = loadDriAddon();
+      let appleClientId;
+      try {
+        // the WindowServer handshake happens on first call; a session with
+        // no WindowServer (SSH into the machine) is where it throws
+        appleClientId = dri.apple.clientId();
+      } catch (err) {
+        return fail(
+          GLError.NO_WINDOWSERVER,
+          `this process has no WindowServer session to import surfaces into (${err.message})`,
+          'Apple-DRI hands the window surface to the WindowServer connection of this\n' +
+            'process, which an SSH session does not have. Run the app from the logged-in\n' +
+            'GUI session; over SSH, indirect GLX is the backend that can work.'
+        );
+      }
+      const AppleDRI = await requireAppleDRI(app.display);
+      if (!AppleDRI) {
+        return fail(
+          GLError.NO_APPLEDRI,
+          `${displayName()} does not have the Apple-DRI extension, so it cannot export a window surface to render into`,
+          'Apple-DRI is XQuartz\'s direct-rendering extension — is this display an\n' +
+            'XQuartz server? Indirect GLX is the backend that can work on any other.'
+        );
+      }
+      const capable = await new Promise((resolve) =>
+        AppleDRI.QueryDirectRenderingCapable(0, (err, answer) => resolve(err ? false : answer))
+      );
+      if (!capable) {
+        return fail(
+          GLError.NO_APPLEDRI,
+          `${displayName()} has Apple-DRI but reports it not direct-rendering capable`,
+          'XQuartz answers this false when its Xplugin backend is not driving a real\n' +
+            'display. Indirect GLX is the backend that can work on such a server.'
+        );
+      }
+      return {
+        direct: true,
+        indirect,
+        flavor: 'appledri',
+        device: null,
+        reason: null,
+        DRI3: null,
+        Present: null,
+        AppleDRI,
+        appleClientId
+      };
+    }
+
     if (!canPassDescriptors(app.display)) {
       // The socket is local; what is missing is the ability to send a
       // descriptor along it. x11 does that through Node's internal
@@ -302,9 +432,6 @@ export function glCapabilities(app) {
       );
     }
 
-    const client = probeDirect(policy);
-    if (!client.ok) return fail(client.code, client.message, client.hint);
-
     const X = app.X;
     const [DRI3, Present] = await Promise.all([requireExt(X, 'dri3'), requireExt(X, 'present')]);
     if (!DRI3 || !Present) {
@@ -325,7 +452,17 @@ export function glCapabilities(app) {
       );
     }
 
-    return { direct: true, indirect, device: client.device, reason: null, DRI3, Present };
+    return {
+      direct: true,
+      indirect,
+      flavor: 'dri3',
+      device: client.device,
+      reason: null,
+      DRI3,
+      Present,
+      AppleDRI: null,
+      appleClientId: null
+    };
   })();
   return app._glCaps;
 }

package/lib/index.js

@@ -55,13 +55,15 @@ import { TextLayout } from './text/layout.js';
 import SvgView from './widgets/svgview.js';
 import { cssColor, cssColorStraight, premultiply } from './color.js';
 
-// rendering context modules register themselves on Drawable. The direct one
-// comes last on purpose: it wraps the 'opengl' factory the indirect one just
-// registered, so that the backend-neutral name can dispatch on glPolicy.
+// rendering context modules register themselves on Drawable. The direct ones
+// come last on purpose: each wraps the 'opengl' factory the one before it
+// registered, so that the backend-neutral name can dispatch on glPolicy —
+// indirect underneath, then the dri3 flavor, then the appledri one on top.
 import './renderingcontext_x11.js';
 import { CanvasGradient, CanvasPattern } from './renderingcontext_2d.js';
 import './renderingcontext_opengl.js';
 import './renderingcontext_gles.js';
+import './renderingcontext_cgl.js';
 
 // One socket write per frame instead of one per request (x11 >= 3.6). A frame
 // is emitted in one synchronous run of _runFrame() and ends with the frame

package/lib/renderingcontext_cgl.js

@@ -0,0 +1,439 @@
+// Direct rendering context, macOS/XQuartz flavor: OpenGL on the GPU through
+// CGL, drawing straight into the window's WindowServer surface, which the
+// server exports over the Apple-DRI extension (lib/appledri.js).
+//
+// The mirror image of the DRI3 flavor (lib/renderingcontext_gles.js): DRI3
+// is client-allocates-and-pushes — GBM buffers travel to the server as
+// dma-buf descriptors and are shown with Present — where Apple-DRI is
+// server-exports-and-client-attaches:
+//
+//   this process                              X server (XQuartz)
+//   ------------                              ------------------
+//   apple.clientId()  --- AppleDRICreateSurface(win, cid) --->  exports the
+//                     <-------------- key[2] ----------------   window's surface
+//   ctx.attach(key)      (import surface + bind CGL context)
+//   gl draws straight into the window's backing store
+//   ctx.flush()          (CGLFlushDrawable — WindowServer composites)
+//                     <--- AppleDRISurfaceNotify ------------   moved/resized/
+//                                                               destroyed
+//
+// After attach, no pixels and no per-frame requests cross the X socket at
+// all. The GL the context speaks is the same WebGL-shaped camelCase table
+// the DRI3 flavor installs — the addon serves both from one `gl` object, and
+// on Apple's GL (4.1 core on Metal, ES2-compatible) the same GLSL ES 1.00
+// shaders compile unchanged — so draw code written against `gl.backend ===
+// 'direct'` runs on either. See docs/context-gles.md#macos.
+//
+// Two structural differences from the GLES flavor, both consequences of the
+// server owning the buffer:
+//
+//  - **The surface exists only while the physical (Quartz) window does**, so
+//    setup is not synchronous: the CGL context is created in the
+//    constructor (and `gl.*` works immediately — an unattached context
+//    compiles shaders and renders to FBOs), but the attach waits for
+//    MapNotify, and `SurfaceNotify(destroyed)` (unmap, frame recreated)
+//    means export-and-attach again. `ready`/`canRender()` report it, and
+//    the existing `onFrameAvailable` contract absorbs the wait.
+//  - **No backpressure from the server**: `flush()` always succeeds
+//    immediately, so a loop that draws whenever it can would spin at 100%
+//    CPU. Rather than a second pacing model, the swap itself closes the
+//    `canRender()` gate for one display period and a timer reopens it —
+//    the same gate IdleNotify drives on Linux, so a draw loop written for
+//    one flavor paces correctly on the other.
+
+import { connectionGone } from './cleanup.js';
+import Drawable from './drawable.js';
+import { GLError, backendFor, glError, loadDriAddon } from './gl.js';
+
+/** pacing fallback where the display's rate is not known (see App#frameInterval) */
+const FALLBACK_FRAME_INTERVAL = 1000 / 60;
+
+/**
+ * The app-level uid -> context routes for AppleDRISurfaceNotify.
+ *
+ * The event is classic (not a GenericEvent, so `_setGenericEventSink` never
+ * sees it), unsolicited (no mask to select), and names its surface by the
+ * **uid** from the CreateSurface reply rather than by window id — so the
+ * per-window `event_consumers` dispatch cannot route it either. One
+ * client-level listener per connection, keyed by uid, is the whole scheme.
+ */
+function appleSurfaceRoutes(app) {
+  if (app._appleSurfaces) return app._appleSurfaces;
+  const routes = new Map();
+  app._appleSurfaces = routes;
+  app.X.on('event', (ev) => {
+    if (ev.name !== 'AppleDRISurfaceNotify') return;
+    routes.get(ev.arg)?._surfaceNotify(ev);
+  });
+  return routes;
+}
+
+class RenderingContextCGL {
+  constructor(window, config = {}) {
+    const app = window.app;
+    const caps = app._glCapsResolved;
+    if (!caps) {
+      throw glError(
+        GLError.CONTEXT_FAILED,
+        "getContext('cgl') needs the direct-rendering probe to have answered, and it has not",
+        `createClient() runs the probe during the handshake when glPolicy could pick the
+direct backend, so a context can be created synchronously afterwards. Under the
+default policy ('indirect') it does not run, and asking for this context by name
+does not make it retroactive. Either:
+
+  const app = await createClient({ glPolicy: 'auto' });   // probe at connect
+  await app.glCapabilities();                             // or ask, once, later`
+      );
+    }
+    if (!caps.direct) throw caps.reason;
+    if (caps.flavor !== 'appledri') {
+      throw glError(
+        GLError.CONTEXT_FAILED,
+        `this connection's direct backend is ${caps.flavor}, not Apple-DRI/CGL`,
+        "getContext('opengl') is the backend-neutral name and picks the right flavor;\n'cgl' asks for this one by name and only exists on macOS/XQuartz."
+      );
+    }
+
+    const dri = loadDriAddon();
+    this.window = window;
+    this.app = app;
+    this.X = window.X;
+    this.dri = dri;
+    this.AppleDRI = caps.AppleDRI;
+    /** which backend this is, for code that runs on either */
+    this.backend = 'direct';
+    /** which direct pipeline, for the curious ('dri3' on Linux) */
+    this.flavor = 'appledri';
+    this.error = null;
+
+    const depth = window.depth || app.display.screen[0].root_depth || 24;
+    if (depth !== 24 && depth !== 32) {
+      throw glError(
+        GLError.CONTEXT_FAILED,
+        `direct rendering needs a 24- or 32-bit window, and this one is ${depth}-bit`,
+        'Create the window with depth 24 (opaque) or 32 (per-pixel alpha, via\napp.findArgbVisual()).'
+      );
+    }
+    this.depth = depth;
+    this._screen = config.screen ?? 0;
+    this._clientId = caps.appleClientId ?? dri.apple.clientId();
+
+    // One CGL context per context object, not a shared one per app: a CGL
+    // context can be attached to exactly one surface, and contexts are cheap
+    // where EGL ones are not. The visible consequence is that GL resources
+    // (programs, textures) are per-window on this flavor where the GLES one
+    // shares them — key caches by the `gl` object identity and both are
+    // covered (docs/context-gles.md#macos).
+    try {
+      this.ctx = new dri.apple.Context({
+        depthSize: config.depthSize ?? config.DEPTH_SIZE ?? 16
+      });
+    } catch (err) {
+      throw glError(
+        GLError.CONTEXT_FAILED,
+        `could not create a CGL context: ${err.message}`,
+        null,
+        err
+      );
+    }
+
+    this._routes = appleSurfaceRoutes(app);
+    this._uid = undefined;
+    this._attached = false;
+    this._pendingSurface = false;
+    this._throttled = false;
+    this._timer = null;
+    this._frameWanted = null;
+    this._destroyed = false;
+
+    /**
+     * Resolves once the window's surface has been exported and attached —
+     * the whole path proven — and rejects with a coded error if it cannot
+     * be. Settles only after the window is mapped: the physical Quartz
+     * window has to exist before the server has a surface to export, so
+     * `map()` first, then `await gl.ready`.
+     */
+    this.ready = new Promise((resolve, reject) => {
+      this._settleReady = (err) => {
+        this._settleReady = null;
+        if (err) reject(err);
+        else resolve(this);
+      };
+    });
+    // a rejection nobody is listening for must not take the process down;
+    // `error` is the other way to find out
+    this.ready.catch(() => {});
+
+    // GL entry points and constants, bound so that this context is the
+    // current one when they run
+    this._installGL();
+    this.makeCurrent();
+
+    // The attach dance: surface after MapNotify, again after a Destroyed
+    // notify once the window is viewable again. `on('map')` also selects
+    // StructureNotify where the window does not have it yet (adopted ids).
+    this._onMap = () => {
+      if (!this._attached && !this._pendingSurface) this._createSurface();
+    };
+    window.on('map', this._onMap);
+    if (window._mapped) this._createSurface();
+  }
+
+  /**
+   * Copy the addon's GL namespace onto this context.
+   *
+   * Same shape as the GLES flavor: every function is wrapped with a currency
+   * check, because another context may have made itself current since the
+   * last call here — `app._glCurrent` is one slot shared by every direct
+   * context on the connection, whichever flavor.
+   */
+  _installGL() {
+    const table = this.dri.gl;
+    for (const key in table) {
+      const value = table[key];
+      if (typeof value !== 'function') {
+        this[key] = value; // GL constants
+        continue;
+      }
+      this[key] = (...args) => {
+        if (this.app._glCurrent !== this) this._bind();
+        return value(...args);
+      };
+    }
+  }
+
+  /**
+   * Ask the server to export the window's surface, then attach to it.
+   *
+   * Called from MapNotify (the physical window now exists) and from the
+   * SurfaceNotify(destroyed) recovery path. Attaching again on the same CGL
+   * context replaces whatever surface it held.
+   */
+  _createSurface() {
+    if (this._destroyed || this.error || this.window._destroyed || connectionGone(this.X)) return;
+    this._pendingSurface = true;
+    this.AppleDRI.CreateSurface(this._screen, this.window.id, this._clientId, (err, surf) => {
+      this._pendingSurface = false;
+      if (this._destroyed || this.window._destroyed) return;
+      if (err) {
+        return this._fail(
+          glError(
+            GLError.CONTEXT_FAILED,
+            `Apple-DRI could not export a surface for this window: ${err.message}`,
+            null,
+            err
+          )
+        );
+      }
+      if (this._uid !== undefined) this._routes.delete(this._uid);
+      this._uid = surf.uid;
+      this._routes.set(surf.uid, this);
+      try {
+        this.ctx.attach(surf.key);
+      } catch (attachErr) {
+        return this._fail(
+          glError(
+            GLError.CONTEXT_FAILED,
+            `could not attach the CGL context to the exported surface: ${attachErr.message}`,
+            null,
+            attachErr
+          )
+        );
+      }
+      this.app._glCurrent = this; // attach leaves the context current
+      this._attached = true;
+      this._settleReady?.(null);
+      this._onFrameAvailable();
+    });
+    this.X.flush?.();
+  }
+
+  /** the app-level route target for this context's SurfaceNotify events */
+  _surfaceNotify(ev) {
+    if (this._destroyed || this.error) return;
+    if (ev.kind === this.AppleDRI.NotifyKind.Changed) {
+      // moved or resized under the surface: refresh the context's idea of it
+      if (this._attached) {
+        try {
+          this.ctx.update();
+        } catch {
+          // a surface torn down between the event and now; the Destroyed
+          // notify that follows is what handles it
+        }
+      }
+      return;
+    }
+    // Destroyed: the Quartz window went away — unmapped, or its frame was
+    // recreated. The context survives; the surface has to be exported and
+    // attached again once there is a window to export.
+    this._attached = false;
+    if (this._uid !== undefined) {
+      this._routes.delete(this._uid);
+      this._uid = undefined;
+    }
+    if (this.window._mapped && !this._pendingSurface) this._createSurface();
+    // not mapped: the 'map' listener picks it up when it is again
+  }
+
+  /**
+   * Make this context current, and pick up a resize.
+   *
+   * Call it at the top of a frame, as on the GLES flavor. A size change
+   * needs no new buffers here — the surface is the window's backing store
+   * and tracks it — but the context has to be told to re-read the geometry.
+   */
+  makeCurrent() {
+    if (this.error || this._destroyed || this.window._destroyed) return this;
+    this._bind();
+    const width = this.window.width;
+    const height = this.window.height;
+    if (width !== this._width || height !== this._height) {
+      this._width = width;
+      this._height = height;
+      if (this._attached) {
+        try {
+          this.ctx.update();
+        } catch {
+          // surface gone; the Destroyed notify re-attaches
+        }
+      }
+    }
+    return this;
+  }
+
+  _bind() {
+    if (this.error || this._destroyed) return;
+    this.ctx.makeCurrent();
+    this.app._glCurrent = this;
+  }
+
+  /**
+   * Is a frame worth drawing right now?
+   *
+   * False until the surface is attached (nowhere to draw to), and false for
+   * one display period after each swap (the pacing gate). `onFrameAvailable`
+   * fires when either turns true.
+   */
+  canRender() {
+    if (this.error || this._destroyed) return false;
+    return this._attached && !this._throttled;
+  }
+
+  /** Called when `canRender()` became true again — attach settled, or the pacing gate reopened. */
+  set onFrameAvailable(fn) {
+    this._frameWanted = fn;
+  }
+
+  get onFrameAvailable() {
+    return this._frameWanted;
+  }
+
+  _onFrameAvailable() {
+    this._frameWanted?.();
+  }
+
+  /**
+   * Show the frame just drawn (CGLFlushDrawable — the WindowServer
+   * composites the surface; no X request is involved).
+   *
+   * Returns false when there is no attached surface yet or the pacing gate
+   * is closed — the same contract as the GLES flavor's "every buffer is with
+   * the server", and `onFrameAvailable` reopens it the same way.
+   */
+  SwapBuffers() {
+    if (this.error || this._destroyed || this.window._destroyed) return false;
+    if (!this._attached || this._throttled) return false;
+    try {
+      this.ctx.flush();
+    } catch (err) {
+      this._fail(glError(GLError.CONTEXT_FAILED, `CGL flush failed: ${err.message}`, null, err));
+      return false;
+    }
+    // The pacing gate: flush() never blocks and the server sends no
+    // done-with-it event, so an unthrottled loop would spin. Close the gate
+    // for most of a display period; the timer reopens it and fires
+    // onFrameAvailable, which is exactly what IdleNotify does on Linux.
+    // Most of one rather than a full one because callers paced by
+    // requestAnimationFrame already wait a display period of their own, and
+    // a full gate in series with it would drop below display rate; at 3/4
+    // the frame clock stays the pacer and this gate only stops the spin.
+    // (ctx.setSwapInterval(1) — a blocking vsync'd flush — remains available
+    // on the raw context for callers who want real vsync.)
+    this._throttled = true;
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      this._throttled = false;
+      this._onFrameAvailable();
+    }, (this.app.frameInterval ?? FALLBACK_FRAME_INTERVAL) * 0.75);
+    return true;
+  }
+
+  swapBuffers() {
+    return this.SwapBuffers();
+  }
+
+  /** The GL renderer string — "Apple M1 Pro" and the like, handy in bug reports. */
+  get renderer() {
+    try {
+      return this.dri.gl.getString(this.dri.GL.RENDERER);
+    } catch {
+      return null;
+    }
+  }
+
+  _fail(err) {
+    if (this.error) return;
+    this.error = err;
+    this._settleReady?.(err);
+  }
+
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+    this.window.removeListener('map', this._onMap);
+    if (this._uid !== undefined) {
+      this._routes.delete(this._uid);
+      this._uid = undefined;
+    }
+    // release the server's reference to the surface; with the window (or the
+    // connection) already gone the server has done it for us
+    if (!this.window._destroyed && !connectionGone(this.X)) {
+      try {
+        this.AppleDRI.DestroySurface(this._screen, this.window.id);
+      } catch {
+        // the connection is closing; the server frees everything with it
+      }
+    }
+    if (this.app._glCurrent === this) this.app._glCurrent = null;
+    try {
+      this.ctx.destroy();
+    } catch {
+      // already torn down
+    }
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+}
+
+Drawable.renderingContextFactory['cgl'] = (window, config) => new RenderingContextCGL(window, config);
+
+// The 'opengl' dispatcher was registered by renderingcontext_gles.js (which
+// index.js imports first); this wrap slots the Apple flavor in ahead of it.
+// The chain: appledri flavor -> this context; everything else -> the GLES
+// module's dispatch, which handles dri3, indirect, off and not-yet-probed.
+const dispatchBelow = Drawable.renderingContextFactory['opengl'];
+Drawable.renderingContextFactory['opengl'] = (window, config) => {
+  const app = window.app;
+  if (backendFor(app) === 'direct' && app._glCapsResolved?.flavor === 'appledri') {
+    return new RenderingContextCGL(window, config);
+  }
+  return dispatchBelow(window, config);
+};
+
+export default RenderingContextCGL;

package/lib/renderingcontext_gles.js

@@ -67,6 +67,13 @@ does not make it retroactive. Either:
       );
     }
     if (!caps.direct) throw caps.reason;
+    if (caps.flavor && caps.flavor !== 'dri3') {
+      throw glError(
+        GLError.CONTEXT_FAILED,
+        `this connection's direct backend is ${caps.flavor}, not DRI3/GLES`,
+        "getContext('opengl') is the backend-neutral name and picks the right flavor;\n'gles' asks for the Linux one by name. On macOS/XQuartz the flavor is 'cgl'\n(lib/renderingcontext_cgl.js), same contract and the same gl surface."
+      );
+    }
 
     const dri = loadDriAddon();
     this.window = window;

package/lib/window.js

@@ -109,6 +109,16 @@ const REFRESH_QUANTILE = 0.25;
 const STALL_TIMEOUT = 2000;
 const STALL_TIMEOUT_FIRST = 250;
 
+/**
+ * MotionNotify detail saying "this is the only motion you get until you ask".
+ *
+ * The core protocol calls it NotifyHint and puts it in the event's detail
+ * byte; node-x11 parses a MotionNotify's detail into `keycode`, the field
+ * that carries a button number on ButtonPress — so this is compared against
+ * `ev.keycode`, not `ev.detail`, which motion events do not have.
+ */
+const MOTION_NOTIFY_HINT = 1;
+
 function rectArea(r) {
   return Math.max(0, r.w) * Math.max(0, r.h);
 }
@@ -493,6 +503,15 @@ export default class Window extends Drawable {
     this._geSinkOpcode = 0;
     // XI2 state, once a window has selected it (see selectXI2)
     this._xi2 = null;
+    // PointerMotionHint bookkeeping (see setMouseHintOnly and
+    // _rearmMotionHint): whether a frame owes the server the QueryPointer
+    // that re-arms the hint, whether one is already in flight, the timestamp
+    // of the hint that asked for it, and the last position delivered — a
+    // reply that repeats it is not an event.
+    this._hintRearm = false;
+    this._hintPollPending = false;
+    this._hintTime = 0;
+    this._hintLast = 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.
@@ -762,6 +781,21 @@ export default class Window extends Drawable {
           if (key.codepoint !== undefined) ev.codepoint = key.codepoint;
         }
       }
+      // the server saying "the pointer moved, and I will say no more about it
+      // until you ask": the event still carries the position it was generated
+      // at, so it is delivered like any other move, but the conversation has
+      // to be picked back up or this is the last one (see _rearmMotionHint)
+      if (eventName === 'mousemove' && ev.keycode === MOTION_NOTIFY_HINT) {
+        this._hintTime = ev.time;
+        this._hintLast = { x: ev.x, y: ev.y };
+        this._hintRearm = true;
+        this._deliverEvent(eventName, ntkev);
+        // the frame that just took the move sends the poll — one per frame,
+        // which is the rate a frame's worth of motion is reduced to anyway.
+        // An uncoalesced window has no frame to hang it on, so it goes now.
+        if (!this._coalesce) this._rearmMotionHint();
+        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).
@@ -1393,6 +1427,9 @@ export default class Window extends Drawable {
     )
       return;
     this._flushCoalesced();
+    // after the flush: the frame's motion has been delivered, so what the
+    // server is asked for now is what happened since
+    if (this._hintRearm) this._rearmMotionHint();
     if (f.needsRedraw) {
       f.needsRedraw = false;
       const ev = {
@@ -1987,6 +2024,9 @@ export default class Window extends Drawable {
     f.rafCbs = [];
     f.needsRedraw = false;
     this._presentPending = false;
+    // a window with no frames left has nothing to send the poll from
+    this._hintRearm = false;
+    this._hintLast = null;
   }
 
   /**
@@ -3252,11 +3292,45 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Trade motion events for round trips: ask the server to report the pointer
+   * moving *once*, and then wait to be asked where it went.
+   *
+   * PointerMotionHint is a two-party protocol. With it selected the server
+   * may send a single MotionNotify carrying detail NotifyHint and then say
+   * nothing more about the pointer until the client asks — so a window that
+   * only sets the bit hears about one move and then silence (issue #319).
+   * ntk holds up the other end: a hinted move is delivered with the position
+   * it carries, and the frame it lands in sends the QueryPointer that lets
+   * the server speak again (see _rearmMotionHint).
+   *
+   * What that buys, and what it costs, are the same thing. Motion stops being
+   * paced by the input device and starts being paced by the connection: one
+   * event per round trip instead of one per hardware sample, which is a large
+   * saving on a link where bytes are scarce — X over ssh, a tunnel, a slow
+   * network — and no saving at all on a local socket, where the poll costs
+   * more bytes than the events it replaced. It also means a handler acts on a
+   * position that is up to one round trip old. Reach for it when bandwidth is
+   * the problem; leave it alone when latency is.
+   *
+   * Two things it is not:
+   *
+   *   - not a substitute for selecting motion. The hint modifies
+   *     PointerMotion, it does not imply it — a window with no `mousemove`
+   *     listener and no PointerMotion in its mask receives nothing either way.
+   *   - not an XI2 control. A window that called `selectXI2(['Motion'])` is
+   *     off the core motion stream entirely (see lib/xi2.js), and the core
+   *     hint has nothing left to thin.
+   */
   setMouseHintOnly(isOn) {
     if (isOn && !(this.eventMask & x11.eventMask.PointerMotionHint)) {
       this.eventMask |= x11.eventMask.PointerMotionHint;
     } else if (!isOn && this.eventMask & x11.eventMask.PointerMotionHint) {
       this.eventMask &= ~x11.eventMask.PointerMotionHint;
+      // the server will report motion on its own again, so no frame owes it a
+      // question. A poll already in flight is left alone: its answer is a
+      // real position, and it is deduped against the last one like any other.
+      this._hintRearm = false;
     } else {
       return this;
     }
@@ -3265,6 +3339,63 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Answer a NotifyHint: ask where the pointer is, which is what re-arms the
+   * server, and deliver the answer if it moved somewhere no event reported.
+   *
+   * The reply is not redundant with the hint that asked for it. Between the
+   * hint being generated and the server processing this request the pointer
+   * may have moved again, and that motion produces no event — it is exactly
+   * what the hint suppressed. Dropped, the last position of a gesture that
+   * ends mid-flight is lost and the window's idea of where the pointer is
+   * stays wrong until it moves again. So the poll's position is delivered as
+   * a motion event when it differs from the last one delivered, and nothing
+   * is emitted when the pointer sat still.
+   *
+   * One poll at a time, and one per frame: a burst of motion cannot queue a
+   * round trip each, and the flag stays raised if a poll is already out, so
+   * the next frame picks it up.
+   */
+  _rearmMotionHint() {
+    if (this._hintPollPending) return;
+    this._hintRearm = false;
+    if (this._destroyed || connectionGone(this.X)) return;
+    this._hintPollPending = true;
+    const time = this._hintTime;
+    this.X.QueryPointer(this.id, (err, pointer) => {
+      this._hintPollPending = false;
+      if (err || this._destroyed || connectionGone(this.X)) return;
+      // the pointer is on another screen: `child` and the window-relative
+      // coordinates are zero by protocol, not a position (core QueryPointer)
+      if (!pointer.sameScreen) return;
+      const last = this._hintLast;
+      if (last && last.x === pointer.childX && last.y === pointer.childY) return;
+      this._hintLast = { x: pointer.childX, y: pointer.childY };
+      this._deliverEvent('mousemove', {
+        type: 6,
+        name: 'MotionNotify',
+        // the poll has no timestamp of its own — QueryPointer's reply carries
+        // no time — so the event is stamped with the hint that prompted it
+        time,
+        keycode: 0,
+        root: pointer.root,
+        wid: this.id,
+        child: pointer.child,
+        rootx: pointer.rootX,
+        rooty: pointer.rootY,
+        x: pointer.childX,
+        y: pointer.childY,
+        buttons: pointer.keyMask,
+        sameScreen: pointer.sameScreen,
+        // built from a reply rather than read off the wire, the way a paced
+        // window's redraw events are
+        synthetic: true,
+        window: this,
+        target: this
+      });
+    });
+  }
+
   queryPointer(callback) {
     this.X.QueryPointer(this.id, callback);
     return this;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "8.3.1",
+  "version": "8.4.1",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "x11": "^4.0.1"
   },
   "optionalDependencies": {
-    "x11-dri": ">=0.2.0 <1"
+    "x11-dri": ">=0.5.0 <1"
   },
   "scripts": {
     "test": "NTK_STRICT_COLORS=1 node --test",