ntk 6.2.0 → 6.4.0

package/lib/glx.js

@@ -1,10 +1,115 @@
-// GLX visual/fbconfig discovery.
+// GLX visual/fbconfig discovery, and the diagnosis of a failed setup.
 //
 // A GLX drawable has to use a visual the GL context was created for, so the
 // visual must be known *before* CreateWindow. This module asks the server
 // (GetFBConfigs, falling back to the GLX 1.2 GetVisualConfigs) instead of
 // shelling out to `glxinfo`, so it works headlessly and in CI.
 
+/**
+ * `err.code` on every error this module and the OpenGL context throw, so
+ * callers can branch on the cause instead of matching on message text.
+ *
+ * - `GLX_NO_EXTENSION` — the server does not have the GLX extension.
+ * - `GLX_INDIRECT_DISABLED` — it has GLX, but refuses indirect contexts,
+ *   which is the only kind that works over the wire. The default on Xorg
+ *   >= 1.17 and Xwayland, and by far the most common failure.
+ * - `GLX_NO_CONFIG` — no visual/fbconfig matches the requested attributes.
+ * - `GLX_CONTEXT_FAILED` — anything else that went wrong in setup.
+ */
+export const GLXError = {
+  NO_EXTENSION: 'GLX_NO_EXTENSION',
+  INDIRECT_DISABLED: 'GLX_INDIRECT_DISABLED',
+  NO_CONFIG: 'GLX_NO_CONFIG',
+  CONTEXT_FAILED: 'GLX_CONTEXT_FAILED'
+};
+
+// `message` says what is wrong in one line; `hint` is the multi-line
+// remedy, printed by the default warning and available to anyone rendering
+// their own fallback UI.
+function glxError(code, message, hint, cause) {
+  const err = new Error(message);
+  err.code = code;
+  if (hint) err.hint = hint;
+  if (cause) err.cause = cause;
+  return err;
+}
+
+const displayName = () => process.env.DISPLAY || 'the X server';
+
+const IGLX_HINT = `Indirect GLX is what ntk draws with: GL commands travel over the X
+connection, since there is no client-side GL library involved. Xorg >= 1.17
+and Xwayland ship with it disabled, and answer GLX CreateContext with
+BadValue. The extension is still present and still advertises GLX 1.4 with a
+full set of fbconfigs, which is why this looks like it should have worked.
+
+To get a server that allows it:
+  under Wayland:  Xwayland :5 +iglx &  then DISPLAY=:5
+  under X:        Xephyr :5 +iglx &    then DISPLAY=:5
+  Xorg:           +iglx on the command line, or
+                  Option "AllowIndirectGLX" "on" in xorg.conf
+  XQuartz:        defaults write org.xquartz.X11 enable_iglx -bool true
+
+Note that on current Linux distros the indirect GL *engine* behind those
+contexts is often gone even with +iglx on — contexts are created but nothing
+rasterizes. See docs/context-opengl.md.`;
+
+/** Turn a failed GLX CreateContext into an error that explains itself. */
+export function diagnoseCreateContext(err, cfg) {
+  // BadValue with value 0 from CreateContext (minor opcode 3) is how a
+  // server without +iglx says "no indirect contexts here" — every other
+  // rejection names the value it disliked
+  if (err?.error === 2 && err.badParam === 0) {
+    return glxError(
+      GLXError.INDIRECT_DISABLED,
+      `${displayName()} has GLX but refuses to create indirect GLX contexts, so there is no OpenGL context to draw with`,
+      IGLX_HINT,
+      err
+    );
+  }
+  const visual = cfg?.visual ? ` for visual 0x${cfg.visual.toString(16)}` : '';
+  return glxError(
+    GLXError.CONTEXT_FAILED,
+    `GLX CreateContext${visual} failed: ${err?.message ?? err}`,
+    null,
+    err
+  );
+}
+
+/**
+ * The console form of a failed GL setup: what went wrong, then how to fix
+ * it. Indented so the remedy reads as one block and not as unrelated log
+ * lines, and ending with the way to take over the handling.
+ */
+export function glxErrorReport(err) {
+  const lines = [`ntk: getContext('opengl') failed — ${err?.message ?? err}`];
+  if (err?.hint) lines.push('', ...err.hint.split('\n').map((l) => (l ? `  ${l}` : l)));
+  lines.push('', `  (await gl.ready to handle this yourself; err.code is ${err?.code ?? 'unset'})`);
+  return lines.join('\n');
+}
+
+/**
+ * Create a GLX context and find out whether it worked.
+ *
+ * CreateContext has no reply, so its failure would otherwise surface as an
+ * unattributed X error plus a misleading GLXBadContext from the MakeCurrent
+ * that follows. node-x11 >= 3.8 takes a callback here; older versions
+ * cannot report it at all, and this resolves optimistically rather than
+ * hanging.
+ */
+export function createContext(GLX, ctx, cfg) {
+  if (GLX.CreateContext.length < 6) {
+    GLX.CreateContext(ctx, cfg.visual, cfg.screen ?? 0, 0, 0);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    GLX.CreateContext(ctx, cfg.visual, cfg.screen ?? 0, 0, 0, (err) => {
+      if (err) reject(diagnoseCreateContext(err, cfg));
+      else resolve();
+      return true; // handled here; keep it away from the app's onXError
+    });
+  });
+}
+
 // defaults applied on top of the caller's spec; `null` means "don't care"
 const DEFAULT_SPEC = {
   DOUBLEBUFFER: true,
@@ -120,8 +225,12 @@ function matchLegacy(configs, spec) {
 export async function chooseGLXConfig(app, spec = {}) {
   const GLX = app.display.GLX;
   if (!GLX) {
-    throw new Error(
-      'GLX: extension not available on this display — indirect GLX is often disabled (X server flag +iglx / AllowIndirectGLX)'
+    throw glxError(
+      GLXError.NO_EXTENSION,
+      `${displayName()} does not have the GLX extension, so it cannot do OpenGL at all`,
+      'A server built without GLX, or started with -extension GLX. This is a\n' +
+        'different problem from indirect GLX being disabled, which is the usual\n' +
+        'one — there the extension is present and CreateContext is what fails.'
     );
   }
 
@@ -135,7 +244,11 @@ export async function chooseGLXConfig(app, spec = {}) {
 
   if (want.visual) {
     const info = visualInfo(screen, want.visual);
-    if (!info) throw new Error(`GLX: visual 0x${want.visual.toString(16)} is not on screen ${screenNum}`);
+    if (!info)
+      throw glxError(
+        GLXError.NO_CONFIG,
+        `GLX: visual 0x${want.visual.toString(16)} is not on screen ${screenNum}`
+      );
     return {
       visual: want.visual,
       depth: info.depth,
@@ -187,8 +300,10 @@ export async function chooseGLXConfig(app, spec = {}) {
   const legacyBest = pick(fromVisuals);
   if (legacyBest) return legacyBest;
 
-  throw new Error(
-    `GLX: no visual on screen ${screenNum} matches ${describe(want)} (server offered ${legacy.length} GLX visuals)`
+  throw glxError(
+    GLXError.NO_CONFIG,
+    `GLX: no visual on screen ${screenNum} matches ${describe(want)} (server offered ${legacy.length} GLX visuals)`,
+    'Relax the spec — DEPTH_SIZE and DOUBLEBUFFER are the usual culprits.'
   );
 }
 

package/lib/index.js

@@ -3,6 +3,7 @@ import x11 from 'x11';
 import App from './app.js';
 import Clipboard from './clipboard.js';
 import { BLANK_CURSOR, CursorCache, cursorNames, cursorShapes, resolveCursorShape } from './cursor.js';
+import { GLXError } from './glx.js';
 import Window from './window.js';
 import { loadLayout } from './yoga.js';
 import { decodeKey, groupForState } from './keyboard.js';
@@ -227,7 +228,9 @@ export {
   premultiply,
   cssLength,
   decodeKey,
-  groupForState
+  groupForState,
+  // the `code` on a failed GL setup: branch on it rather than on the message
+  GLXError
 };
 // The layout engine ntk lays HtmlView out with — downstream layout consumers
 // (e.g. the react-x11 renderer) must import it from here rather than from

package/lib/renderingcontext_opengl.js

@@ -1,5 +1,5 @@
 import Drawable from './drawable.js';
-import { chooseGLXConfig } from './glx.js';
+import { GLXError, chooseGLXConfig, createContext, glxErrorReport } from './glx.js';
 
 // Indirect GLX rendering context exposing an OpenGL 1.4-style api.
 // Note: many modern X servers ship with indirect GLX disabled — see README.
@@ -14,9 +14,11 @@ class RenderingContextOpenGL {
     const X = window.X;
     const GLX = window.display.GLX;
     if (!GLX) {
-      throw new Error(
-        "getContext('opengl'): the X server has no GLX extension — indirect GLX is often disabled (+iglx / AllowIndirectGLX)"
+      const err = new Error(
+        `getContext('opengl'): ${process.env.DISPLAY || 'the X server'} does not have the GLX extension, so it cannot do OpenGL at all`
       );
+      err.code = GLXError.NO_EXTENSION;
+      throw err;
     }
 
     this.window = window;
@@ -82,9 +84,21 @@ class RenderingContextOpenGL {
 
       const ctx = X.AllocID();
       this.contextId = ctx;
-      GLX.CreateContext(ctx, cfg.visual, cfg.screen ?? 0, 0, 0);
+      // CreateContext first, and on its own: it is the request a server with
+      // indirect GLX disabled rejects, and going on to MakeCurrent would bury
+      // that under a GLXBadContext about the context that was never created
+      await createContext(GLX, ctx, cfg).catch((err) => {
+        this.contextId = 0; // nothing to destroy
+        throw err;
+      });
       const tag = await new Promise((resolve, reject) => {
-        GLX.MakeCurrent(window.id, ctx, 0, (err, contextTag) => (err ? reject(err) : resolve(contextTag)));
+        GLX.MakeCurrent(window.id, ctx, 0, (err, contextTag) => {
+          if (!err) return resolve(contextTag);
+          const failed = new Error(`GLX MakeCurrent failed: ${err.message}`);
+          failed.code = GLXError.CONTEXT_FAILED;
+          failed.cause = err;
+          reject(failed);
+        });
       });
 
       this.contextTag = tag;
@@ -97,9 +111,7 @@ class RenderingContextOpenGL {
     this.ready.catch((err) => {
       this.error = err;
       queue.length = 0;
-      console.warn(
-        `ntk: getContext('opengl') failed: ${err.message} (await gl.ready to handle this yourself)`
-      );
+      console.warn(glxErrorReport(err));
     });
   }
 

package/lib/window.js

@@ -355,6 +355,20 @@ export default class Window extends Drawable {
     // (see docs/window.md "Frames, coalescing and slow connections")
     this._coalesce = args.coalesceEvents !== false;
     this._frameSyncEnabled = args.frameSync !== false;
+    // _NET_WM_SYNC_REQUEST (see enableSyncRequest): the counter the window
+    // manager watches, the value it last asked for, and the watchdog that
+    // guarantees an answer even when nothing repaints
+    this._syncCounter = null;
+    this._syncRequestAtom = 0;
+    this._syncPending = null;
+    this._syncWatchdog = null;
+    // Present-based blits (see enablePresent): the extension objects, the
+    // XFixes region reused as the update region, and the serial the server
+    // echoes back in its completion events
+    this._presentExt = null;
+    this._fixesExt = null;
+    this._updateRegion = 0;
+    this._presentSerial = 0;
     this.frameInterval = args.frameInterval ?? 16;
     this.frameLatency = null;
     this._frame = {
@@ -364,7 +378,12 @@ export default class Window extends Drawable {
       inFlight: false, // fence round-trip awaiting the server's reply
       timer: null,
       scheduled: false,
-      needsRedraw: false
+      needsRedraw: false,
+      // minimum inter-blit pacing: when the last blit went out, and the timer
+      // that guarantees a blit held back by the interval still lands.
+      // -Infinity so the first blit after construction is never delayed.
+      lastPresentAt: -Infinity,
+      presentTimer: null
     };
 
     if (!args.id) {
@@ -482,6 +501,17 @@ export default class Window extends Drawable {
     if (args.alwaysOnTop) {
       this.setAlwaysOnTop(true);
     }
+    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
+      // the earliest. `await wnd.enableSyncRequest()` when that is too close.
+      this.enableSyncRequest().catch((err) => this.app.options.onXError?.(err));
+    }
+    if (args.present && !args.id) {
+      // fire and forget: until the extensions answer, blits use CopyArea,
+      // which is what they would have done anyway
+      this.enablePresent().catch((err) => this.app.options.onXError?.(err));
+    }
 
     X.event_consumers[this.id] = this;
     this.on('event', (ev) => {
@@ -537,7 +567,10 @@ export default class Window extends Drawable {
       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);
+      if (eventName === 'message') {
+        this._emitCloseRequest(ntkev);
+        this._handleSyncRequest(ntkev);
+      }
       // anything drawn during the handlers becomes visible in one blit
       if (this._dirty) this._present();
     });
@@ -812,8 +845,13 @@ export default class Window extends Drawable {
    *  - a timer: at most one paced frame per `frameInterval` ms, so a fast
    *    local server doesn't get redraws at input-device rate.
    *
-   * Discrete events (mousedown, keydown, ...) bypass the timer for latency,
-   * but their blits still respect the fence via _present().
+   * Discrete events (mousedown, keydown, ...) bypass the timer for latency:
+   * the first blit after a quiet moment goes out with the handler's own
+   * requests. Their blits are still bounded, by the fence and by a minimum
+   * inter-blit interval (also `frameInterval`) — see _present(). Without that
+   * interval a stream of discrete events blits at round-trip rate, which on a
+   * local server is several hundred per second, and under a compositor every
+   * blit is a recomposite.
    */
   _scheduleFrame() {
     const f = this._frame;
@@ -831,7 +869,15 @@ export default class Window extends Drawable {
 
   _runFrame() {
     const f = this._frame;
-    if (!f.pending.size && !f.rafCbs.length && !f.needsRedraw && !this._dirty && !this._presentPending) return;
+    if (
+      !f.pending.size &&
+      !f.rafCbs.length &&
+      !f.needsRedraw &&
+      !this._dirty &&
+      !this._presentPending &&
+      this._syncPending == null
+    )
+      return;
     this._flushCoalesced();
     if (f.needsRedraw) {
       f.needsRedraw = false;
@@ -854,6 +900,9 @@ export default class Window extends Drawable {
       for (const entry of cbs) entry.cb(now);
     }
     if (this._dirty || this._presentPending) this._presentNow();
+    // covers a window with no backing store, and a resize that changed
+    // nothing: _presentNow did not run, but the frame is still "handled"
+    this._ackSyncRequest();
     this._armFence();
     this._armTimer();
   }
@@ -952,9 +1001,10 @@ export default class Window extends Drawable {
         f.inFlight = false;
         this.frameLatency = performance.now() - start;
         if (this._presentPending) {
-          // a blit deferred while the fence was in flight: show it now
-          this._presentNow();
-          this._armFence();
+          // a blit deferred while the fence was in flight: show it as soon as
+          // the minimum inter-blit interval allows (immediately when the last
+          // blit is already older than that, which is the common case)
+          this._present();
         }
         if ((f.pending.size || f.rafCbs.length || f.needsRedraw) && !f.timer) this._scheduleFrame();
       });
@@ -978,6 +1028,36 @@ export default class Window extends Drawable {
       clearTimeout(f.timer);
       f.timer = null;
     }
+    if (f.presentTimer) {
+      clearTimeout(f.presentTimer);
+      f.presentTimer = null;
+    }
+    if (this._syncWatchdog) {
+      clearTimeout(this._syncWatchdog);
+      this._syncWatchdog = null;
+    }
+    // Destroying the counter releases any Await the window manager is
+    // blocked in, so a window that goes away mid-drag does not strand it.
+    if (this._syncCounter && this._sync) {
+      const counter = this._syncCounter;
+      this._syncCounter = null;
+      this._syncPending = null;
+      safeRelease(this.X, () => {
+        this._sync.DestroyCounter(counter);
+        this.X.ReleaseID(counter);
+      });
+    }
+    if (this._updateRegion && this._fixesExt) {
+      const region = this._updateRegion;
+      this._updateRegion = 0;
+      this._presentExt = null;
+      const fixes = this._fixesExt;
+      this._fixesExt = null;
+      safeRelease(this.X, () => {
+        fixes.DestroyRegion(region);
+        this.X.ReleaseID(region);
+      });
+    }
     f.pending.clear();
     f.rafCbs = [];
     f.needsRedraw = false;
@@ -1014,9 +1094,11 @@ export default class Window extends Drawable {
    * Drawing the response inside the event handler costs a frame less latency:
    * the blit goes out with the handler's own requests (see the `_present()`
    * at the end of the event dispatch) instead of waiting for the next paced
-   * frame. Drawing it while a frame is in flight costs a frame's *work* for
-   * nothing: the present is deferred until the ack and coalesces with the
-   * one already pending, so only the last paint is ever seen. So `false`
+   * frame — provided the last blit is at least `frameInterval` old, which is
+   * what a discrete input arriving out of the blue always is. Drawing it while
+   * a frame is in flight costs a frame's *work* for nothing: the present is
+   * deferred until the ack and coalesces with the one already pending, so only
+   * the last paint is ever seen. So `false`
    * means "draw it now", `true` means "leave it to the frame clock" — which
    * is how a burst of discrete events (a spun wheel) paints its first notch
    * immediately and folds the rest into one catch-up frame.
@@ -1031,15 +1113,129 @@ export default class Window extends Drawable {
 
   _present() {
     if (!this._backing) return;
-    if (this._frame.inFlight) {
-      // the server hasn't confirmed the previous frame yet — defer the blit
-      this._presentPending = true;
+    const wait = this._presentWait();
+    if (this._frame.inFlight || wait > 0) {
+      // the server hasn't confirmed the previous frame yet, or the last blit
+      // was too recent — defer, and leave a wakeup behind
+      this._deferPresent(wait);
       return;
     }
     this._presentNow();
     this._armFence();
   }
 
+  /**
+   * How long until the next blit may go out; 0 when it may go now.
+   *
+   * The gate is `frameInterval`, the same knob that paces frames, so
+   * `frameInterval: 0` keeps the old fence-only behaviour — a caller who asked
+   * for no timer gate gets none here either.
+   */
+  _presentWait() {
+    const min = this.frameInterval;
+    if (!(min > 0)) return 0;
+    const since = performance.now() - this._frame.lastPresentAt;
+    return since >= min ? 0 : min - since;
+  }
+
+  /**
+   * Hold a blit back, and guarantee it still happens.
+   *
+   * This is the only place `_presentPending` is set, because every deferral has
+   * to leave a wakeup behind: the fence reply when the fence is what we are
+   * waiting on, this timer when the interval is. Nothing else reschedules a
+   * present — `_scheduleFrame()` bails while a frame timer is armed, and
+   * neither reschedule condition (in `_armFence`'s reply or `_armTimer`'s
+   * callback) looks at the present. Without the timer the last blit of a burst
+   * would simply never go out, leaving stale pixels on screen.
+   */
+  _deferPresent(wait) {
+    this._presentPending = true;
+    if (wait <= 0) return; // waiting on the fence: its reply blits this
+    const f = this._frame;
+    if (f.presentTimer) return; // already armed
+    f.presentTimer = setTimeout(() => {
+      f.presentTimer = null;
+      if (!this._presentPending && !this._dirty) return; // someone blitted it
+      const again = this._presentWait();
+      if (again > 0) return this._deferPresent(again); // a paced frame re-stamped
+      if (f.inFlight) return; // the fence ack is closer; it will blit
+      this._presentNow();
+      this._armFence();
+    }, wait);
+    if (typeof f.presentTimer.unref === 'function') f.presentTimer.unref();
+  }
+
+  /**
+   * Blit with the Present extension instead of `CopyArea`.
+   *
+   * A frame's dirty rectangles become one `PresentPixmap` with an update
+   * region, in place of one `CopyArea` per rectangle. Two things follow:
+   * a frame is a fixed two requests however fragmented the damage is, and
+   * `_blitList`'s bounding-box collapse becomes unnecessary — its whole
+   * premise is "each rectangle costs a request", so with Present the exact
+   * rectangles are sent and pixels outside them are never touched.
+   *
+   * Presents are also scheduled by the server against the display's refresh
+   * rather than executed on arrival, so a burst cannot produce more updates
+   * than the output can show; the server drops superseded frames itself.
+   *
+   * Worth being precise about what this does *not* do: under a compositing
+   * manager the window is redirected, so this schedules the server's copy
+   * into the redirect pixmap — the compositor still composites on its own
+   * schedule. Aligning with *that* is what `_NET_WM_SYNC_REQUEST`'s extended
+   * counters are for.
+   *
+   * Opt-in via `createWindow({ present: true })`, and inert unless both
+   * Present and XFixes are available — blits fall back to `CopyArea`, which
+   * stays correct at all times, so the two paths can even alternate.
+   *
+   * @returns {Promise<Window>}
+   */
+  enablePresent() {
+    if (this._presentExt || this._destroyed) return Promise.resolve(this);
+    const X = this.X;
+    const need = (name) =>
+      new Promise((resolve) => X.require(name, (err, ext) => resolve(err ? null : ext)));
+    return Promise.all([need('present'), need('fixes')]).then(([present, fixes]) => {
+      if (!present || !fixes || this._destroyed) return this; // stay on CopyArea
+      this._updateRegion = X.AllocID();
+      safeRelease(X, () => fixes.CreateRegion(this._updateRegion, []));
+      this._presentExt = present;
+      this._fixesExt = fixes;
+      return this;
+    });
+  }
+
+  /**
+   * The Present form of the blit. Returns false when it did not happen, so
+   * the caller falls back to CopyArea — which is also what runs before the
+   * extensions have answered.
+   */
+  _presentWithExtension(rects) {
+    const P = this._presentExt;
+    if (!P || !this._fixesExt || !this._updateRegion) return false;
+    safeRelease(this.X, () => {
+      this._fixesExt.SetRegion(
+        this._updateRegion,
+        rects.map((r) => ({ x: r.x, y: r.y, width: r.w, height: r.h }))
+      );
+      this._presentExt.Pixmap(this.id, this._backing.id, {
+        serial: ++this._presentSerial,
+        update: this._updateRegion,
+        // Option.Copy forces the copy path. Without it the server may *flip*
+        // the pixmap to the screen and take ownership of it until an
+        // IdleNotify — and ntk reuses one grow-only backing pixmap, so
+        // drawing into it while the server owned it would paint the screen
+        // directly. Removing this needs a swap chain, not just a smaller diff.
+        options: P.Option.Copy
+        // targetMsc stays 0: "the next vblank", which is what we want. An
+        // explicit target only adds ways to fall behind.
+      });
+    });
+    return true;
+  }
+
   _presentNow() {
     this._presentPending = false;
     if (!this._backing) return;
@@ -1061,13 +1257,27 @@ export default class Window extends Drawable {
       if (x1 > x0 && y1 > y0) clamped.push({ x: x0, y: y0, w: x1 - x0, h: y1 - y0 });
     }
     if (!clamped.length) return;
-    const rects = this._blitList(clamped);
-    // a paced frame can fire after the connection started closing
-    safeRelease(this.X, () => {
-      for (const r of rects) {
-        this.X.CopyArea(this._backing.id, this.id, this._presentGc, r.x, r.y, r.x, r.y, r.w, r.h);
-      }
-    });
+    // Stamped here rather than at the call sites so it is a true inter-blit
+    // interval across all three of them, and only when pixels really move — a
+    // present that copies nothing must not push the next one out.
+    this._frame.lastPresentAt = performance.now();
+    // Present sends the exact rectangles in one request, so the bounding-box
+    // collapse — which trades pixels for fewer requests — has nothing to buy
+    if (!this._presentWithExtension(clamped)) {
+      const rects = this._blitList(clamped);
+      // a paced frame can fire after the connection started closing
+      safeRelease(this.X, () => {
+        for (const r of rects) {
+          this.X.CopyArea(this._backing.id, this.id, this._presentGc, r.x, r.y, r.x, r.y, r.w, r.h);
+        }
+      });
+    }
+    // Queued behind whichever of the two put the pixels on their way, so the
+    // window manager hears about the new size only once the server has drawn
+    // it. Both paths must reach this: a window using Present *and*
+    // _NET_WM_SYNC_REQUEST would otherwise never answer, and the resize would
+    // stall.
+    this._ackSyncRequest();
   }
 
   /**
@@ -1504,6 +1714,10 @@ export default class Window extends Drawable {
    *
    * `WM_DELETE_WINDOW` needs none of this by hand: listening for the
    * `'close'` event adds the protocol and decodes the message for you.
+   * `_NET_WM_SYNC_REQUEST` likewise has a real opt-in — `enableSyncRequest()`
+   * / `createWindow({ syncRequest: true })`. Adding that atom here instead
+   * advertises a protocol this window cannot answer, which is worse than not
+   * advertising it: the counter the window manager looks for is missing.
    *
    * Replaces the whole list. `addProtocol`/`removeProtocol` are the
    * accumulating forms, and the ones to reach for: the property is a *set*,
@@ -2537,6 +2751,116 @@ export default class Window extends Drawable {
    * existed — keeps behaving exactly as it did, rather than suddenly
    * acquiring a second handler that destroys it.
    */
+  /**
+   * Opt into `_NET_WM_SYNC_REQUEST` (EWMH §6.2): let the window manager pace
+   * an interactive resize to how fast this window actually repaints.
+   *
+   * Without it a WM has no idea when a resize has been drawn, so it either
+   * throws ConfigureNotify at the client as fast as the pointer moves — and
+   * the window lags behind the frame the user is dragging — or guesses with a
+   * timer. With it, the WM sends a serial before each resize and waits for
+   * this window to echo it back once the new size is on screen.
+   *
+   * Also available as `createWindow({ syncRequest: true })`. This is the
+   * awaitable form, for when `map()` follows immediately: the counter and the
+   * `_NET_WM_SYNC_REQUEST_COUNTER` property have to exist before the window
+   * leaves the withdrawn state, because that is when the WM reads them.
+   *
+   * Silently does nothing when the server has no SYNC extension — a WM that
+   * finds no counter simply drives the resize the old way.
+   *
+   * Only basic (single-counter) synchronization is implemented. The extended
+   * two-counter form buys frame-timing feedback rather than resize pacing, and
+   * its odd/even parity rules freeze the window if they are ever got wrong; a
+   * compositor that supports it falls back to basic mode on its own when the
+   * property holds one counter.
+   *
+   * @returns {Promise<Window>}
+   */
+  enableSyncRequest() {
+    if (this._syncCounter || this._destroyed) return Promise.resolve(this);
+    const X = this.X;
+    return new Promise((resolve, reject) => {
+      X.require('sync', (err, Sync) => {
+        if (err || !Sync || this._destroyed) return resolve(this); // no SYNC: stay quiet
+        this._sync = Sync;
+        const counter = X.AllocID();
+        safeRelease(X, () => Sync.CreateCounter(counter, 0));
+        this._syncCounter = counter;
+        // The dispatch path compares against both atoms, and node-x11 caches
+        // interned atoms per connection, so this is one round trip and no more.
+        this.atom('WM_PROTOCOLS').catch(() => {});
+        this._withAtoms(['_NET_WM_SYNC_REQUEST_COUNTER', '_NET_WM_SYNC_REQUEST'], (atoms) => {
+          this._syncRequestAtom = atoms._NET_WM_SYNC_REQUEST;
+          safeRelease(X, () =>
+            X.ChangeProperty(
+              0,
+              this.id,
+              atoms._NET_WM_SYNC_REQUEST_COUNTER,
+              X.atoms.CARDINAL,
+              32,
+              [counter]
+            )
+          );
+          // property first, protocol second: a window manager that sees the
+          // protocol advertised must always find the counter behind it
+          this.addProtocol('_NET_WM_SYNC_REQUEST').then(() => resolve(this), reject);
+        });
+      });
+    });
+  }
+
+  /**
+   * The window manager asking us to report when a resize has been painted.
+   *
+   * Only the value is recorded here — acknowledging now would claim a frame
+   * that has not been drawn. `_ackSyncRequest` sends it once the pixels are on
+   * their way. EWMH is explicit that only the *last* message is acknowledged,
+   * so a newer request simply overwrites an older one.
+   */
+  _handleSyncRequest(ev) {
+    if (!this._syncCounter || ev.format !== 32) return;
+    const X = this.X;
+    if (!X.atoms.WM_PROTOCOLS || ev.message_type !== X.atoms.WM_PROTOCOLS) return;
+    if (!this._syncRequestAtom || ev.data?.[0] !== this._syncRequestAtom) return;
+    // data[2] is the low half of the 64-bit request number, data[3] the high
+    this._syncPending = ev.data[3] * 0x100000000 + ev.data[2];
+    // Not every request leads to a repaint — a move, or a resize to the size
+    // we already are, leaves nothing dirty and no frame scheduled. The
+    // watchdog turns a missed acknowledgement into a stutter instead of a
+    // window manager that waits forever.
+    this._armSyncWatchdog();
+  }
+
+  _armSyncWatchdog() {
+    if (this._syncWatchdog || this._syncPending == null) return;
+    this._syncWatchdog = setTimeout(() => {
+      this._syncWatchdog = null;
+      this._ackSyncRequest();
+    }, Math.max(this.frameInterval, 16) * 2);
+    if (typeof this._syncWatchdog.unref === 'function') this._syncWatchdog.unref();
+  }
+
+  /**
+   * Answer the window manager's last sync request.
+   *
+   * Called after the requests that repaint have been queued, never before: X
+   * runs a client's requests in order, so a SetCounter queued behind the
+   * copies is executed behind them too, which is exactly the "having handled
+   * all repainting" the spec asks for. (It rides the same output batch, which
+   * is flushed before the event loop polls — no manual flush needed.)
+   */
+  _ackSyncRequest() {
+    const value = this._syncPending;
+    if (value == null || !this._syncCounter || !this._sync) return;
+    this._syncPending = null;
+    if (this._syncWatchdog) {
+      clearTimeout(this._syncWatchdog);
+      this._syncWatchdog = null;
+    }
+    safeRelease(this.X, () => this._sync.SetCounter(this._syncCounter, value));
+  }
+
   _emitCloseRequest(ev) {
     if (ev.format !== 32 || !this.listenerCount('close')) return;
     // node-x11 caches interned atoms per connection, so these are the ids

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "parse-color": "^1.0.0",
     "pngjs": "^7.0.0",
     "postcss": "^8.5.23",
-    "x11": "^3.7.0",
+    "x11": "^3.8.0",
     "yoga-layout": "^3.2.1"
   },
   "scripts": {