ntk 8.4.0 → 8.4.1

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);
           });
         }
       });

package/lib/gl.js

@@ -171,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

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.4.0",
+  "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",