ntk 2.2.0 → 3.0.0

package/lib/window.js

@@ -1,308 +1,642 @@
-var util = require('util');
-var Drawable = require('./drawable');
-var xevents = require('./events_map');
-var x11 = require('x11');
-
-module.exports = Window;
-
-function Window(app, args) {
-  if (!args) args = {};
-
-  if (args.id) {
-    var cached = Window.cache[args.id];
-    if (cached) {
-      // TODO: check event mask, if more events in args - update it
-      return cached;
-    }
-  }
-
-  if (this.constructor !== Window) return new Window(app, args);
-
-  Drawable.call(this);
-
-  // shortcuts
-  var X = app.X;
-  this.X = X;
-  this.app = app;
-  var display = app.display;
-  this.display = display;
-  this._readyPromiseResolve = null;
-  this._readyPromiseReject = null;
-  var self = this;
-  this._readyPromise = new Promise(function(resolve, reject) {
-    self._readyPromiseResolve = resolve;
-    self._readyPromiseReject = reject;
-  });
-
-  var parent, parentId;
-
-  if (!args.parent) parentId = display.screen[0].root;
-  else {
-    parentId = args.parent.id;
-  }
-
-  if (!args.id) {
-    this.id = X.AllocID();
-    this.eventMask = x11.eventMask.StructureNotify;
-
-    for (ntkEventName in xevents.maskCamelCase) {
-      if (typeof args[ntkEventName] == 'function') {
-        this.eventMask = this.eventMask | xevents.maskCamelCase[ntkEventName];
-        this.on(xevents.toSnake[ntkEventName], args[ntkEventName]);
-      }
-    }
-
-    this.width = args.width ? args.width : 800;
-    this.height = args.height ? args.height : 800;
-    this.x = args.x ? args.x : 0;
-    this.y = args.y ? args.y : 0;
-    X.CreateWindow(this.id, parentId, this.x, this.y, this.width, this.height, 0, 0, 0, 0, {
-      eventMask: this.eventMask
-    });
-  } else {
-    this.id = args.id;
-    // populate width and height
-    X.GetGeometry(this.id, function(err, res) {
-      self.width = res.width;
-      self.height = res.height;
-      self.x = res.xPos;
-      self.y = res.yPos;
-      self._readyPromiseResolve();
-    });
-  }
-
-  Window.cache[this.id] = this;
-
-  if (args.title) {
-    this.setTitle(args.title);
-  }
-
-  X.event_consumers[this.id] = this;
-  this.on('event', function(ev) {
-    var ntkev = ev; // todo: clone
-    ntkev.window = this;
-    ntkev.target = this;
-    var eventName = xevents.eventName[ev.type];
-    if (eventName) {
-      // TODO cleanup
-      // also it seems that in keysym module not all keys have valid unicode values
-      if (eventName == 'keydown') {
-        var evKeysym = X.keycode2keysyms[ev.keycode];
-        var shift = ev.buttons & 1;
-        var capsLock = ev.buttons & 2;
-        var capital = (capsLock && !shift) || (shift && !capsLock);
-        var keysym = require('keysym');
-        var symInd = capital ? 1 : 0; // TODO: AltGr & other modifiers to use syms 2, 3, 4 etc
-        var entry = keysym.fromKeysym(evKeysym[symInd]);
-        if (entry) {
-          ev.codepoint = entry.unicode;
-        }
-      }
-      this.emit(eventName, ntkev);
-    } else {
-      console.log('Unknown event: ', ev.type, ev.name);
-    }
-  });
-  this.on('child-event', function(ev) {
-    var ntkev = {};
-    var eventName = xevents.eventName[ev.type];
-    ntkev.parent = this;
-    ntkev.window = new Window(app, { id: ev.wid });
-    // wait until we know that we track correct x,y,w,h values
-    ntkev.window._readyPromise.then(function() {
-      self.emit(eventName, ntkev);
-    });
-  });
-
-  this.on('newListener', function(name) {
-    // check eventMask and add handler if missing
-    var eventMask = xevents.mask[name];
-    if ((eventMask & self.eventMask) == 0) {
-      self.eventMask |= eventMask;
-      X.ChangeWindowAttributes(self.id, { eventMask: this.eventMask }, function() {});
-    }
-  });
-
-  this.on('resize', function(ev) {
-    self.width = ev.width;
-    self.height = ev.height;
-    self.x = ev.x;
-    self.y = ev.y;
-  });
-
-  this.on('map', () => (this._mapped = true));
-  this.on('unmap', () => (this._mapped = false));
-
-  if (typeof this.width !== 'undefined') {
-    this._readyPromiseResolve();
-  }
-}
-util.inherits(Window, Drawable);
-
-Window.cache = [];
-
-Window.prototype.map = function() {
-  this.X.MapWindow(this.id);
-  return this;
-};
-
-Window.prototype.unmap = function() {
-  this.X.UnmapWindow(this.id);
-  return this;
-};
-
-Window.prototype.resize = function(w, h) {
-  this.X.ResizeWindow(this.id, w, h);
-  return this;
-};
-
-const changeAttributesPropNames =
-  'backgroundPixmap backgroundPixel borderPixmap borderPixel bitGravity winGravity backingStore backingPlanes backingPixel overrideRedirect saveUnder eventMask doNotPropagateMask colormap cursor';
-
-Window.prototype.setState = function(newState) {
-  if (!this._mapped && newState.visible) {
-    this.map();
-  }
-  if (newState.visible === false && this._mapped) {
-    this.unmap();
-  }
-
-  // 'x y width height borderWidth stackMode sibling'
-  const configureProps = {};
-  let needConfigureWindow = false;
-  if (newState.x !== void 0 && this.x !== newState.x) {
-    needConfigureWindow = true;
-    configureProps.x = newState.x;
-  }
-  if (newState.y !== void 0 && this.y !== newState.y) {
-    needConfigureWindow = true;
-    configureProps.y = newState.y;
-  }
-  if (newState.width !== void 0 && this.width !== newState.width) {
-    needConfigureWindow = true;
-    configureProps.width = newState.width;
-  }
-  if (newState.height !== void 0 && this.height !== newState.height) {
-    needConfigureWindow = true;
-    newState.height = configureProps.height;
-  }
-  if (needConfigureWindow) {
-    console.log(configureProps);
-    this.X.ConfigureWindow(this.id, configureProps);
-  }
-
-  //const changeAttributesProps = {};
-  //let needChangeAttributes = false;
-  //this.X.ChangeWindowAttributes(this.id, changeAttributesProps);
-  // todo others
-};
-
-Window.prototype.inspect = function() {
-  return `[Window ${this.id}]`;
-};
-
-Window.prototype.move = function(x, y) {
-  this.X.MoveWindow(this.id, x, y);
-  return this;
-};
-
-Window.prototype.moveResize = function(x, y, w, h) {
-  this.X.MoveResizeWindow(this.id, x, y, w, h);
-  return this;
-};
-
-Window.prototype.setTitle = function(title) {
-  this.X.ChangeProperty(
-    0,
-    this.id,
-    this.display.client.atoms.WM_NAME,
-    this.display.client.atoms.STRING,
-    8,
-    title
-  );
-  return this;
-};
-
-Window.prototype.setMouseHintOnly = function(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;
-  } else {
-    return this;
-  }
-  this.X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, function() {});
-  return this;
-};
-
-Window.prototype.queryPointer = function(callback) {
-  this.X.QueryPointer(this.id, callback);
-  return this;
-};
-
-Window.prototype.grabPointer = function() {
-  this.X.GrabPointer(this.id, true, x11.eventMask.PointerMotion, 0, 1, 0, 0, 0);
-};
-
-Window.prototype.reparentTo = function(newParent, x, y) {
-  this.X.ReparentWindow(this.id, newParent.id, x, y);
-};
-
-Window.prototype.destroy = function() {
-  this.X.DestroyWindow(this.id);
-};
-
-Window.prototype.queryTree = function(callback) {
-  var app = this.app;
-  this.X.QueryTree(this.id, function(err, tree) {
-    if (err) return callback(err);
-    var children = tree.children.map(function(id) {
-      return new Window(app, { id: id });
-    });
-    var parent = new Window(app, { id: tree.parent });
-    // note that this root may be different from app.rootWindow() because there can be multiple screens (and roots)
-    var root = new Window(app, { id: tree.root });
-    var readyPromises = children.map(w => w._readyPromise);
-    readyPromises.push(parent._readyPromise);
-    readyPromises.push(root._readyPromise);
-    Promise.all(readyPromises).then(function() {
-      callback(null, { parent: parent, root: root, children: children });
-    });
-  });
-  return this;
-};
-
-Window.prototype.message = function(type, data) {
-  // send ClientMessage
-  throw new Error('not implemented');
-};
-
-Window.prototype.createPixmap = function(params) {
-  var Pixmap = require('../lib/pixmap.js');
-  var pixmapParams = Object.assign({}, params);
-  pixmapParams.parent = pixmapParams.parent || this;
-  pixmapParams.width = pixmapParams.width || this.width;
-  pixmapParams.height = pixmapParams.height || this.height;
-  // TODO: use window depth
-  pixmapParams.depth = pixmapParams.depth || 32;
-  return new Pixmap(this.app, pixmapParams);
-};
-
-Window.prototype.createWindow = function(params) {
-  var windowParams = Object.assign({}, params);
-  windowParams.parent = windowParams.parent || this;
-  return new Window(this.app, windowParams);
-};
-
-Window.prototype.setActions = function() {
-  var set_property = require('x11-prop').set_property;
-  var X = this.X;
-  var wid = this.id;
-  X.InternAtom(false, '_NET_WM_ACTION_CLOSE', function(err, _NET_WM_ACTION_CLOSE) {
-    X.InternAtom(false, 'WM_DELETE_WINDOW', function(err, WM_DELETE_WINDOW) {
-      //set_property(X, wid, '_NET_WM_ALLOWED_ACTIONS', 'ATOM', 32, [_NET_WM_ACTION_CLOSE]);
-      console.log('Setting WM_PROTOCOLS');
-      set_property(X, wid, 'WM_PROTOCOLS', 'ATOM', 32, [WM_DELETE_WINDOW]);
-    });
-  });
-};
+import keysym from 'keysym';
+import x11 from 'x11';
+
+import { safeRelease } from './cleanup.js';
+import Drawable from './drawable.js';
+import Pixmap from './pixmap.js';
+import * as xevents from './events_map.js';
+
+export default class Window extends Drawable {
+  // one wrapper per X window id and connection: constructing a Window for a
+  // known id returns the cached instance
+  static cache = new Map();
+
+  constructor(app, args = {}) {
+    if (args.id) {
+      const cached = Window.cache.get(args.id);
+      // TODO: check event mask, if more events in args - update it
+      if (cached) return cached;
+    }
+
+    super();
+
+    const X = app.X;
+    this.X = X;
+    this.app = app;
+    this.display = app.display;
+    this._mapped = false;
+    this._readyPromiseResolve = null;
+    this._readyPromise = new Promise((resolve) => {
+      this._readyPromiseResolve = resolve;
+    });
+
+    const parentId = args.parent ? args.parent.id : app.display.screen[0].root;
+
+    // double buffering (see docs/window.md): windows we created get a
+    // backing pixmap when a 2d context is requested, unless opted out
+    this._foreign = !!args.id;
+    this._backingOptOut = args.backingStore === false;
+    this._backing = null;
+    this._dirty = false;
+    this._presentPending = false;
+
+    // frame clock state: coalesced events, synthetic redraws and
+    // requestAnimationFrame callbacks are delivered in paced frames
+    // (see docs/window.md "Frames, coalescing and slow connections")
+    this._coalesce = args.coalesceEvents !== false;
+    this._frameSyncEnabled = args.frameSync !== false;
+    this.frameInterval = args.frameInterval ?? 16;
+    this.frameLatency = null;
+    this._frame = {
+      pending: new Map(), // coalescible event name -> merged event
+      rafCbs: [],
+      rafId: 0,
+      inFlight: false, // fence round-trip awaiting the server's reply
+      timer: null,
+      scheduled: false,
+      needsRedraw: false
+    };
+
+    if (!args.id) {
+      this.id = X.AllocID();
+      this.eventMask = x11.eventMask.StructureNotify;
+
+      for (const ntkEventName in xevents.maskCamelCase) {
+        if (typeof args[ntkEventName] === 'function') {
+          this.eventMask |= xevents.maskCamelCase[ntkEventName];
+          this.on(xevents.toSnake[ntkEventName], args[ntkEventName]);
+        }
+      }
+
+      this.width = args.width ?? 800;
+      this.height = args.height ?? 800;
+      this.x = args.x ?? 0;
+      this.y = args.y ?? 0;
+      X.CreateWindow(this.id, parentId, this.x, this.y, this.width, this.height, 0, 0, 0, 0, {
+        // NorthWest bit gravity: keep the old content anchored during
+        // resize instead of discarding it (less flicker between the resize
+        // and our redraw)
+        bitGravity: 1,
+        eventMask: this.eventMask
+      });
+    } else {
+      this.id = args.id;
+      this.eventMask = 0;
+      // populate width and height
+      X.GetGeometry(this.id, (err, res) => {
+        if (!err) {
+          this.width = res.width;
+          this.height = res.height;
+          this.x = res.xPos;
+          this.y = res.yPos;
+        }
+        this._readyPromiseResolve();
+      });
+    }
+
+    Window.cache.set(this.id, this);
+
+    if (args.title) {
+      this.setTitle(args.title);
+    }
+
+    X.event_consumers[this.id] = this;
+    this.on('event', (ev) => {
+      const ntkev = ev; // todo: clone
+      ntkev.window = this;
+      ntkev.target = this;
+      const eventName = xevents.eventName[ev.type];
+      if (!eventName) return;
+      // geometry bookkeeping happens on the raw stream so wnd.x/y/width/height
+      // are current even while a user-facing 'resize' event sits coalesced
+      if (eventName === 'resize') {
+        this.width = ev.width;
+        this.height = ev.height;
+        this.x = ev.x;
+        this.y = ev.y;
+      }
+      // double-buffered windows serve expose events from the backing pixmap
+      // — user code is only asked to redraw when the content is invalid
+      if (eventName === 'expose' && this._backing) {
+        this._handleExpose(ev);
+        return;
+      }
+      // TODO cleanup
+      // also it seems that in keysym module not all keys have valid unicode values
+      if (eventName === 'keydown') {
+        const evKeysym = X.keycode2keysyms[ev.keycode];
+        const shift = ev.buttons & 1;
+        const capsLock = ev.buttons & 2;
+        const capital = (capsLock && !shift) || (shift && !capsLock);
+        const symInd = capital ? 1 : 0; // TODO: AltGr & other modifiers to use syms 2, 3, 4 etc
+        const entry = evKeysym && keysym.fromKeysym(evKeysym[symInd]);
+        if (entry) {
+          ev.codepoint = entry.unicode;
+        }
+      }
+      if (this._coalesce && xevents.coalesce[eventName]) {
+        this._enqueueCoalesced(eventName, ntkev);
+        return;
+      }
+      // deliver buffered state events before a discrete one so handlers see
+      // them in the order they happened (a drag sees the move, then the up)
+      this._flushCoalesced();
+      this.emit(eventName, ntkev);
+      // anything drawn during the handlers becomes visible in one blit
+      if (this._dirty) this._present();
+    });
+
+    this.on('child-event', (ev) => {
+      const eventName = xevents.eventName[ev.type];
+      const ntkev = {
+        parent: this,
+        window: new Window(app, { id: ev.wid })
+      };
+      // wait until we know that we track correct x,y,w,h values
+      ntkev.window._readyPromise.then(() => {
+        this.emit(eventName, ntkev);
+      });
+    });
+
+    this.on('newListener', (name) => {
+      // extend the server-side event mask if this event needs it
+      const eventMask = xevents.mask[name];
+      if (!eventMask) return;
+      if ((eventMask & this.eventMask) === 0) {
+        this.eventMask |= eventMask;
+        X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, () => {});
+      }
+    });
+
+    this.on('map', () => (this._mapped = true));
+    this.on('unmap', () => (this._mapped = false));
+    this.on('destroy', () => {
+      this._forget();
+      this._teardownFrame();
+      // the server frees window-backed pictures with the window — let
+      // contexts drop their wrappers without issuing FreePicture
+      this.emit('_destroyed');
+    });
+
+    if (typeof this.width !== 'undefined') {
+      this._readyPromiseResolve();
+    }
+  }
+
+  _forget() {
+    Window.cache.delete(this.id);
+    delete this.X.event_consumers[this.id];
+  }
+
+  /**
+   * 2d contexts on windows draw into a backing pixmap by default and blit to
+   * the window in single CopyArea requests (after event handlers return, and
+   * coalesced per event-loop tick otherwise) — no clear-then-draw flicker.
+   * Expose events are served from the pixmap without invoking user handlers;
+   * an 'expose' (and 'draw') event is emitted only when a real redraw is
+   * needed (first paint, resize). Opt out with
+   * `createWindow({ backingStore: false })`.
+   */
+  getContext(name, ...args) {
+    if (name === '2d' && !this._backing && !this._backingOptOut && !this._foreign) {
+      this._enableBackingStore();
+    }
+    return super.getContext(name, ...args);
+  }
+
+  _enableBackingStore() {
+    this._dirty = false;
+    this._backingValid = false;
+    this._presentScheduled = false;
+    this._backedW = this.width;
+    this._backedH = this.height;
+
+    this._presentGc = this.X.AllocID();
+    this.X.CreateGC(this._presentGc, this.id, { graphicsExposures: 0 });
+    this._allocBacking(this.width, this.height);
+
+    // the redraw cycle is driven by Expose interception — make sure the
+    // server sends them even if user code only listens to 'draw'
+    if (!(this.eventMask & x11.eventMask.Exposure)) {
+      this.eventMask |= x11.eventMask.Exposure;
+      this.X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, () => {});
+    }
+
+    this.on('resize', (ev) => {
+      if (ev.width === this._backedW && ev.height === this._backedH) return;
+      this._backedW = ev.width;
+      this._backedH = ev.height;
+      this._allocBacking(ev.width, ev.height);
+      this._backingValid = false;
+      this._requestRedraw();
+    });
+  }
+
+  // grow-only backing pixmap (re)allocation; new area is cleared to white
+  _allocBacking(w, h) {
+    const cur = this._backing;
+    if (cur && cur.width >= w && cur.height >= h) return;
+    const newW = Math.max(w, cur ? cur.width : 0);
+    const newH = Math.max(h, cur ? cur.height : 0);
+    const pixmap = new Pixmap(this.app, {
+      parent: this,
+      width: newW,
+      height: newH,
+      depth: this.display.screen[0].root_depth
+    });
+    if (!this._clearGc) {
+      // reusable across reallocs: a GC is valid for any drawable of the
+      // same screen and depth (node-x11 has no FreeGC request)
+      this._clearGc = this.X.AllocID();
+      this.X.CreateGC(this._clearGc, pixmap.id, {
+        foreground: this.display.screen[0].white_pixel,
+        graphicsExposures: 0
+      });
+    }
+    this.X.PolyFillRectangle(pixmap.id, this._clearGc, [0, 0, newW, newH]);
+    if (cur) cur.destroy();
+    this._backing = pixmap;
+    this._backingValid = false;
+    // contexts re-bind their pictures to the new pixmap
+    this.emit('_backing');
+  }
+
+  _handleExpose(ev) {
+    if (this._backingValid) {
+      this.X.CopyArea(this._backing.id, this.id, this._presentGc, ev.x, ev.y, ev.x, ev.y, ev.width, ev.height);
+    } else {
+      this._requestRedraw();
+    }
+  }
+
+  // ask user code to repaint (full window), on the next paced frame
+  _requestRedraw() {
+    this._frame.needsRedraw = true;
+    this._scheduleFrame();
+  }
+
+  // called by rendering contexts after each drawing operation
+  _markDirty() {
+    if (!this._backing) return;
+    this._dirty = true;
+    this._backingValid = true;
+    if (this._presentScheduled) return;
+    // coalesce draws that happen outside event handlers into one blit
+    this._presentScheduled = true;
+    setImmediate(() => {
+      this._presentScheduled = false;
+      if (this._dirty) this._present();
+    });
+  }
+
+  /*
+   * Frame clock. Noisy events (see events_map coalesce), synthetic redraws
+   * and requestAnimationFrame callbacks are delivered in "frames", paced by
+   * two independent gates:
+   *
+   *  - a fence: a cheap request with a reply (GetInputFocus) sent after each
+   *    frame; X processes requests in order, so its reply confirms the
+   *    server consumed everything the frame drew. At most one fence is in
+   *    flight — on a slow connection frames degrade to one per round-trip
+   *    instead of queueing a trail of stale updates.
+   *  - 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().
+   */
+  _scheduleFrame() {
+    const f = this._frame;
+    if (f.scheduled || f.inFlight || f.timer) return;
+    f.scheduled = true;
+    setImmediate(() => {
+      f.scheduled = false;
+      // gates may have been armed after this got scheduled (work queued
+      // from inside a running frame, e.g. a rAF loop re-registering) —
+      // the fence reply / timer expiry will reschedule then
+      if (f.inFlight || f.timer) return;
+      this._runFrame();
+    });
+  }
+
+  _runFrame() {
+    const f = this._frame;
+    if (!f.pending.size && !f.rafCbs.length && !f.needsRedraw && !this._dirty && !this._presentPending) return;
+    this._flushCoalesced();
+    if (f.needsRedraw) {
+      f.needsRedraw = false;
+      const ev = {
+        x: 0,
+        y: 0,
+        width: this.width,
+        height: this.height,
+        synthetic: true,
+        window: this,
+        target: this
+      };
+      this.emit('draw', ev);
+      this.emit('expose', ev);
+    }
+    if (f.rafCbs.length) {
+      const cbs = f.rafCbs;
+      f.rafCbs = [];
+      const now = performance.now();
+      for (const entry of cbs) entry.cb(now);
+    }
+    if (this._dirty || this._presentPending) this._presentNow();
+    this._armFence();
+    this._armTimer();
+  }
+
+  _enqueueCoalesced(name, ev) {
+    const pending = this._frame.pending;
+    const prev = pending.get(name);
+    if (!prev) {
+      ev.coalesced = [ev];
+      if (xevents.coalesce[name] === 'union') {
+        ev.rects = [{ x: ev.x, y: ev.y, width: ev.width, height: ev.height }];
+      }
+      pending.set(name, ev);
+    } else if (xevents.coalesce[name] === 'union') {
+      prev.coalesced.push(ev);
+      prev.rects.push({ x: ev.x, y: ev.y, width: ev.width, height: ev.height });
+      const x2 = Math.max(prev.x + prev.width, ev.x + ev.width);
+      const y2 = Math.max(prev.y + prev.height, ev.y + ev.height);
+      prev.x = Math.min(prev.x, ev.x);
+      prev.y = Math.min(prev.y, ev.y);
+      prev.width = x2 - prev.x;
+      prev.height = y2 - prev.y;
+    } else {
+      // keep-last: the newest event wins, older ones ride along
+      ev.coalesced = prev.coalesced;
+      ev.coalesced.push(ev);
+      pending.set(name, ev);
+    }
+    this._scheduleFrame();
+  }
+
+  _flushCoalesced() {
+    const pending = this._frame.pending;
+    if (!pending.size) return;
+    this._frame.pending = new Map();
+    // resize first: geometry-dependent handlers (re-layout) run before repaints
+    for (const name of ['resize', 'expose']) {
+      const ev = pending.get(name);
+      if (ev) {
+        pending.delete(name);
+        this.emit(name, ev);
+      }
+    }
+    for (const [name, ev] of pending) this.emit(name, ev);
+  }
+
+  _armFence() {
+    if (!this._frameSyncEnabled) return;
+    const f = this._frame;
+    if (f.inFlight) return;
+    const start = performance.now();
+    safeRelease(this.X, () => {
+      f.inFlight = true;
+      this.X.GetInputFocus(() => {
+        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();
+        }
+        if ((f.pending.size || f.rafCbs.length || f.needsRedraw) && !f.timer) this._scheduleFrame();
+      });
+    });
+  }
+
+  _armTimer() {
+    if (!(this.frameInterval > 0)) return;
+    const f = this._frame;
+    if (f.timer) return;
+    f.timer = setTimeout(() => {
+      f.timer = null;
+      if (f.pending.size || f.rafCbs.length || f.needsRedraw) this._scheduleFrame();
+    }, this.frameInterval);
+    if (typeof f.timer.unref === 'function') f.timer.unref();
+  }
+
+  _teardownFrame() {
+    const f = this._frame;
+    if (f.timer) {
+      clearTimeout(f.timer);
+      f.timer = null;
+    }
+    f.pending.clear();
+    f.rafCbs = [];
+    f.needsRedraw = false;
+    this._presentPending = false;
+  }
+
+  /**
+   * DOM-style requestAnimationFrame: `cb(now)` runs on this window's next
+   * paced frame — at most once per `frameInterval` ms and with at most one
+   * frame's requests unacknowledged by the server, so animation loops adapt
+   * to connection latency instead of flooding a slow link.
+   * Returns an id for cancelAnimationFrame().
+   */
+  requestAnimationFrame(cb) {
+    const f = this._frame;
+    const id = ++f.rafId;
+    f.rafCbs.push({ id, cb });
+    this._scheduleFrame();
+    return id;
+  }
+
+  cancelAnimationFrame(id) {
+    const f = this._frame;
+    const idx = f.rafCbs.findIndex((entry) => entry.id === id);
+    if (idx !== -1) f.rafCbs.splice(idx, 1);
+  }
+
+  _present() {
+    if (!this._backing) return;
+    if (this._frame.inFlight) {
+      // the server hasn't confirmed the previous frame yet — defer the blit
+      this._presentPending = true;
+      return;
+    }
+    this._presentNow();
+    this._armFence();
+  }
+
+  _presentNow() {
+    this._presentPending = false;
+    if (!this._backing) return;
+    this._dirty = false;
+    const w = Math.min(this.width, this._backing.width);
+    const h = Math.min(this.height, this._backing.height);
+    // a paced frame can fire after the connection started closing
+    safeRelease(this.X, () => {
+      this.X.CopyArea(this._backing.id, this.id, this._presentGc, 0, 0, 0, 0, w, h);
+    });
+  }
+
+  map() {
+    this.X.MapWindow(this.id);
+    return this;
+  }
+
+  unmap() {
+    this.X.UnmapWindow(this.id);
+    return this;
+  }
+
+  resize(w, h) {
+    this.X.ResizeWindow(this.id, w, h);
+    return this;
+  }
+
+  move(x, y) {
+    this.X.MoveWindow(this.id, x, y);
+    return this;
+  }
+
+  moveResize(x, y, w, h) {
+    this.X.MoveResizeWindow(this.id, x, y, w, h);
+    return this;
+  }
+
+  setState(newState) {
+    if (newState.visible && !this._mapped) {
+      this.map();
+    }
+    if (newState.visible === false && this._mapped) {
+      this.unmap();
+    }
+
+    const configureProps = {};
+    let needConfigureWindow = false;
+    if (newState.x !== undefined && this.x !== newState.x) {
+      needConfigureWindow = true;
+      configureProps.x = newState.x;
+    }
+    if (newState.y !== undefined && this.y !== newState.y) {
+      needConfigureWindow = true;
+      configureProps.y = newState.y;
+    }
+    if (newState.width !== undefined && this.width !== newState.width) {
+      needConfigureWindow = true;
+      configureProps.width = newState.width;
+    }
+    if (newState.height !== undefined && this.height !== newState.height) {
+      needConfigureWindow = true;
+      configureProps.height = newState.height;
+    }
+    if (needConfigureWindow) {
+      this.X.ConfigureWindow(this.id, configureProps);
+    }
+
+    // TODO: map other window attributes ( border, gravity, cursor etc )
+    // via ChangeWindowAttributes
+  }
+
+  setTitle(title) {
+    this.X.ChangeProperty(
+      0,
+      this.id,
+      this.X.atoms.WM_NAME,
+      this.X.atoms.STRING,
+      8,
+      title
+    );
+    return this;
+  }
+
+  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;
+    } else {
+      return this;
+    }
+    this.X.ChangeWindowAttributes(this.id, { eventMask: this.eventMask }, () => {});
+    return this;
+  }
+
+  queryPointer(callback) {
+    this.X.QueryPointer(this.id, callback);
+    return this;
+  }
+
+  grabPointer() {
+    this.X.GrabPointer(this.id, true, x11.eventMask.PointerMotion, 0, 1, 0, 0, 0);
+  }
+
+  reparentTo(newParent, x, y) {
+    this.X.ReparentWindow(this.id, newParent.id, x, y);
+  }
+
+  queryTree(callback) {
+    const app = this.app;
+    this.X.QueryTree(this.id, (err, tree) => {
+      if (err) return callback(err);
+      const children = tree.children.map((id) => new Window(app, { id }));
+      const parent = new Window(app, { id: tree.parent });
+      // note that this root may be different from app.rootWindow() because
+      // there can be multiple screens (and roots)
+      const root = new Window(app, { id: tree.root });
+      const readyPromises = [...children, parent, root].map((w) => w._readyPromise);
+      Promise.all(readyPromises).then(() => {
+        callback(null, { parent, root, children });
+      });
+    });
+    return this;
+  }
+
+  createPixmap(params = {}) {
+    return new Pixmap(this.app, {
+      parent: this,
+      width: this.width,
+      height: this.height,
+      // TODO: use window depth
+      depth: 32,
+      ...params
+    });
+  }
+
+  createWindow(params = {}) {
+    return new Window(this.app, { parent: this, ...params });
+  }
+
+  // opt in to the WM_DELETE_WINDOW protocol: the window manager sends a
+  // 'message' event instead of killing the connection when the user closes
+  // the window
+  setActions() {
+    const X = this.X;
+    const wid = this.id;
+    X.InternAtom(false, 'WM_PROTOCOLS', (err, WM_PROTOCOLS) => {
+      X.InternAtom(false, 'WM_DELETE_WINDOW', (err2, WM_DELETE_WINDOW) => {
+        if (err || err2) return;
+        const data = Buffer.alloc(4);
+        data.writeUInt32LE(WM_DELETE_WINDOW, 0);
+        X.ChangeProperty(0, wid, WM_PROTOCOLS, X.atoms.ATOM, 32, data);
+      });
+    });
+  }
+
+  destroy() {
+    this._forget();
+    this._teardownFrame();
+    this.emit('_destroyed');
+    if (this._backing) {
+      this._backing.destroy();
+      this._backing = null;
+    }
+    safeRelease(this.X, () => this.X.DestroyWindow(this.id));
+  }
+
+  [Symbol.dispose]() {
+    this.destroy();
+  }
+
+  inspect() {
+    return `[Window ${this.id}]`;
+  }
+}