ntk 7.4.0 → 7.6.0

package/lib/app.js

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

package/lib/events_map.js

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

package/lib/renderingcontext_2d.js

@@ -1396,14 +1396,35 @@ class RenderingContext2d {
   }
 
   /**
-   * Composite shaped glyph runs onto this context, honouring the clip.
+   * Composite glyph runs onto this context, honouring the clip. This is
+   * the primitive `fillText` and `TextLayout.draw` are built on, and it is
+   * public: the run shape below is a documented contract
+   * (docs/text.md#glyph-runs), so renderers that position glyphs
+   * themselves — a terminal grid, a tabular column — can hand-build runs
+   * instead of shaping.
+   *
+   * @param {number} op Render.PictOp (`ctx.Render.PictOp.Over` for normal text)
+   * @param {Picture} src source picture the glyphs paint with — a solid
+   *   (`ctx.createSolidPicture(r, g, b, a)`, premultiplied 0..1) or a gradient
+   * @param {Array<{run, x, y, textRendering?}>} positioned runs in visual
+   *   order; `x`/`y` is the run's baseline origin in device space. `run` is
+   *   `{ font, size, glyphs }` — a `Font`, a pixel size, and glyphs
+   *   `{ id, ax, dx, dy }` in drawing order: `id` a font glyph id
+   *   (`Font.shape()`'s `glyphs[].id`, or `Font.glyphIdFor(cp)`), `ax` the
+   *   pen advance in px, `dx`/`dy` the drawing offset from the pen position
+   *   (y-up: positive `dy` raises the glyph). The pen starts at `x`; each
+   *   glyph inks at `(pen + dx, y - dy)` and then advances it by `ax`.
+   *   `Font.shape()` returns runs of exactly this shape; extra fields
+   *   (`codePoints`, `width`, …) are ignored. `textRendering` optionally
+   *   overrides the bitmap/vector routing per run (docs/text.md).
    *
    * CompositeGlyphs writes straight to the destination picture, so it has
    * no way to consult our clip mask — text drawn through it used to spill
    * out of clipped boxes while every fill and stroke stayed inside. With a
    * clip active, render the glyph coverage into the scratch a8 mask
    * instead, intersect that with the clip, and paint the real source
-   * through the result — the same shape as _fillPolys.
+   * through the result — the same shape as _fillPolys. A rectangular clip
+   * takes the server-side fast path below instead of the mask.
    */
   drawGlyphs(op, src, positioned) {
     const app = this.window.app;
@@ -1652,6 +1673,80 @@ class RenderingContext2d {
     this._fillPolys(flattenPath(tmp._cmds, this._m), "nonzero");
   }
 
+  /**
+   * Fill a batch of axis-aligned rectangles: `fillRect` once per rectangle
+   * semantically — fillStyle, globalAlpha, the composite op, the clip and
+   * damage reporting all apply — but priced for the "many small rectangles
+   * per frame" caller (issue #253): terminal cell backgrounds, sparkline
+   * bars, heat maps, row striping.
+   *
+   * `rects` is an array of `[x, y, w, h]` quadruples or one flat
+   * `[x0, y0, w0, h0, x1, ...]` array; rectangles with non-positive width
+   * or height are skipped.
+   *
+   * A solid-colour fillStyle under an identity transform and a rectangular
+   * (or absent) clip compiles the whole list into a single
+   * `Render.FillRectangles`, where N `fillRect` calls cost N composites.
+   * Gradient/Picture styles, transforms and non-rectangular clips fall
+   * back to that `fillRect` loop, so the answer is always right and only
+   * the request count varies.
+   */
+  fillRects(rects) {
+    if (!rects || !rects.length || this.globalAlpha <= 0) return;
+    // normalize to one flat list, dropping empty rectangles up front — the
+    // wire encodes width and height unsigned, so a negative would wrap
+    const flat = [];
+    if (Array.isArray(rects[0])) {
+      for (const r of rects) {
+        if (r[2] > 0 && r[3] > 0) flat.push(r[0], r[1], r[2], r[3]);
+      }
+    } else {
+      for (let i = 0; i + 3 < rects.length; i += 4) {
+        if (rects[i + 2] > 0 && rects[i + 3] > 0)
+          flat.push(rects[i], rects[i + 1], rects[i + 2], rects[i + 3]);
+      }
+    }
+    if (!flat.length) return;
+
+    const clip = this._clips.length ? this._clipRect() : null;
+    if (
+      !matIsIdentity(this._m) ||
+      !isPlainColor(this._fillStyle) ||
+      (this._clips.length && !clip)
+    ) {
+      for (let i = 0; i < flat.length; i += 4)
+        this.fillRect(flat[i], flat[i + 1], flat[i + 2], flat[i + 3]);
+      return;
+    }
+    if (clip && (clip.w === 0 || clip.h === 0)) return; // clipped away
+    const R = this.Render;
+    if (clip) {
+      R.SetPictureClipRectangles(this.picture.id, 0, 0, [
+        clip.x,
+        clip.y,
+        clip.w,
+        clip.h,
+      ]);
+    }
+    // globalAlpha folds into the premultiplied colour — scaling all four
+    // components is exactly what compositing at that opacity means, for
+    // any composite op (the mask slot would only scale the source the same
+    // way)
+    const color = this._foldedColor(this._fillStyle);
+    // stay under the server's maximum request size
+    const chunk = 10000 * 4;
+    for (let i = 0; i < flat.length; i += chunk) {
+      R.FillRectangles(
+        this._op(),
+        this.picture.id,
+        color,
+        i === 0 && flat.length <= chunk ? flat : flat.slice(i, i + chunk),
+      );
+    }
+    if (clip) this._resetPictureClip();
+    this._markDirty();
+  }
+
   strokeRect(x, y, w, h) {
     const m = this._m;
     if (m[0] === 1 && m[1] === 0 && m[2] === 0 && m[3] === 1) {

package/lib/surface.js

@@ -1,5 +1,6 @@
 import Picture from './picture.js';
 import Pixmap from './pixmap.js';
+import { safeRelease } from './cleanup.js';
 
 /**
  * An offscreen drawing surface: a pixmap, its Picture, and enough of the
@@ -103,6 +104,67 @@ export class Surface {
     return this.pixmap.getContext(name, ...args);
   }
 
+  /**
+   * Scroll the pixels of `src` (surface coordinates, `{x, y, width, height}`)
+   * by (dx, dy) in place, server-side: one CopyArea of the band that
+   * survives the shift, in place of the caller re-drawing everything that
+   * merely moved. Returns true when the copy was issued; false means
+   * "nothing survives the shift here", and the caller repaints `src` exactly
+   * as it would have without this method — every refusal is the status quo.
+   *
+   * Refused when the delta is fractional (a sub-pixel shift changes every
+   * pixel, so there is nothing to copy), when it is zero, when nothing of
+   * `src` survives the shift after clamping to the surface, or on a
+   * destroyed surface.
+   *
+   * This is `Window#scrollRegion` for a retained offscreen surface, minus
+   * the damage bookkeeping a pixmap does not have: the caller draws the
+   * exposed strip and composites as usual. The overlapping self-copy is
+   * fully defined — pixmap contents cannot be occluded, and the server
+   * fetches the source region before storing. The copy goes out with a
+   * shared graphicsExposures: 0 GC — one per app and depth, created on
+   * first use and released with the connection, where a default GC would
+   * emit a NoExposure event per copy — and in-order with the caller's
+   * follow-up drawing of the exposed strip on the same connection.
+   */
+  copyWithin(src, dx, dy) {
+    if (this._destroyed) return false;
+    if (!Number.isInteger(dx) || !Number.isInteger(dy) || (dx === 0 && dy === 0)) return false;
+    const x0 = Math.max(0, Math.floor(src.x));
+    const y0 = Math.max(0, Math.floor(src.y));
+    const x1 = Math.min(this.width, Math.ceil(src.x + src.width));
+    const y1 = Math.min(this.height, Math.ceil(src.y + src.height));
+    // the band that survives: dest = clamped src ∩ (clamped src + delta)
+    const dstX0 = Math.max(x0, x0 + dx);
+    const dstY0 = Math.max(y0, y0 + dy);
+    const dstX1 = Math.min(x1, x1 + dx);
+    const dstY1 = Math.min(y1, y1 + dy);
+    if (dstX1 <= dstX0 || dstY1 <= dstY0) return false;
+    const X = this.app.X;
+    // a GC is valid for any drawable of its depth on the screen, so one per
+    // app and depth serves every surface — the upload-GC pattern in image.js
+    const gcs = (this.app._surfaceCopyGC ??= {});
+    safeRelease(X, () => {
+      let gc = gcs[this.depth];
+      if (!gc) {
+        gc = gcs[this.depth] = X.AllocID();
+        X.CreateGC(gc, this.pixmap.id, { graphicsExposures: 0 });
+      }
+      X.CopyArea(
+        this.pixmap.id,
+        this.pixmap.id,
+        gc,
+        dstX0 - dx,
+        dstY0 - dy,
+        dstX0,
+        dstY0,
+        dstX1 - dstX0,
+        dstY1 - dstY0
+      );
+    });
+    return true;
+  }
+
   destroy() {
     if (this._destroyed) return;
     this._destroyed = true;

package/lib/text/font.js

@@ -240,6 +240,27 @@ export default class Font {
     return this.fk.hasGlyphForCodePoint(codepoint);
   }
 
+  /**
+   * Glyph id for a codepoint, or `null` when this face does not cover it —
+   * the lookup twin of `hasGlyph`, for callers that position glyphs
+   * themselves (a terminal grid, a tabular column) and hand runs straight
+   * to `ctx.drawGlyphs` without shaping. See docs/text.md#glyph-runs.
+   *
+   * `null` rather than 0: fontkit resolves an uncovered codepoint to the
+   * `.notdef` glyph, and a caller building runs wants "not covered" as a
+   * branch (pick a fallback face) rather than as a tofu box discovered on
+   * screen. This is a cmap lookup only — no shaping, so no ligatures,
+   * kerning or contextual forms; text that needs those goes through
+   * `shape()`.
+   *
+   * @param {number} codepoint Unicode codepoint (`str.codePointAt(i)`)
+   * @returns {number|null} font glyph id, as `shape()` would report in `glyphs[].id`
+   */
+  glyphIdFor(codepoint) {
+    if (!this.fk.hasGlyphForCodePoint(codepoint)) return null;
+    return this.fk.glyphForCodePoint(codepoint).id;
+  }
+
   /**
    * Shape a run of text: returns glyphs with pixel-space positioning.
    * RTL runs come back in visual (left-to-right drawing) order.

package/lib/window.js

@@ -7,6 +7,17 @@ import { packIcons, unpackIcons } from './imagedata.js';
 import Pixmap from './pixmap.js';
 import * as xevents from './events_map.js';
 import { decodeKey } from './keyboard.js';
+import {
+  DEFAULT_XI2_EVENTS,
+  POINTER_EMULATED,
+  ScrollTracker,
+  WHEEL_BUTTONS,
+  normalizeXI2Types,
+  scrollAxes,
+  toNtkEvent,
+  wheelEvent,
+  xi2EventName
+} from './xi2.js';
 
 /**
  * How many rectangles a frame's dirty region is allowed to hold.
@@ -435,10 +446,16 @@ export default class Window extends Drawable {
     this._updateRegion = 0;
     this._presentSerial = 0;
     this._presentEid = 0;
+    // Generic Events (type 35) carry an extension opcode where a core event
+    // carries its code, so they are routed by opcode: Present's completions,
+    // XI2's device events, and whatever else selects them later.
+    this._geHandlers = new Map();
     // A direct GL context's swap chain, when one is presenting on this window
-    // (see _setGenericEventSink)
+    // — an override ahead of that table (see _setGenericEventSink)
     this._geSink = null;
     this._geSinkOpcode = 0;
+    // XI2 state, once a window has selected it (see selectXI2)
+    this._xi2 = null;
     // The vblank clock (see _onPresentComplete): the period learnt from
     // completion events, the samples it is drawn from, and the latch the
     // watchdog sets when completions stop arriving.
@@ -592,6 +609,14 @@ export default class Window extends Drawable {
     if (args.alwaysOnTop) {
       this.setAlwaysOnTop(true);
     }
+    if (args.xi2) {
+      // fire and forget: until the extension answers, the window is on core
+      // events, which is where it would have been anyway. `await
+      // wnd.selectXI2()` is the form that says whether the server has XI2.
+      this.selectXI2(args.xi2 === true ? undefined : args.xi2).catch((err) =>
+        this.app.options.onXError?.(err)
+      );
+    }
     if (args.syncRequest && !args.id) {
       // fire and forget: the window manager only reads the counter when it
       // starts managing the window, and map() is the caller's next line at
@@ -613,19 +638,20 @@ export default class Window extends Drawable {
 
     X.event_consumers[this.id] = this;
     this.on('event', (ev) => {
-      // Present speaks in X Generic Events, which carry an extension opcode
-      // and a sub-type where a core event carries its code — the name table
-      // below cannot see them, and they are not events user code asked for
+      // Present and XI2 speak in X Generic Events, which carry an extension
+      // opcode and a sub-type where a core event carries its code — the name
+      // table below cannot see them, so they are routed by opcode instead
       if (ev.type === 35) {
         // A direct GL context presenting on this window selected these events
         // itself and owns the pixmaps they name, so they are its to read — and
         // it is the only user of Present there, a GL window having no backing
-        // store to blit.
+        // store to blit. Hence an override rather than another table entry:
+        // it claims the same extension the window's own blit path uses.
         if (this._geSink && ev.extension === this._geSinkOpcode) {
           this._geSink.handleEvent(ev);
-        } else if (this._presentExt && ev.extension === this._presentExt.majorOpcode) {
-          this._handlePresentEvent(ev);
+          return;
         }
+        this._geHandlers.get(ev.extension)?.(ev);
         return;
       }
       const ntkev = ev; // todo: clone
@@ -659,9 +685,12 @@ export default class Window extends Drawable {
           if (key.codepoint !== undefined) ev.codepoint = key.codepoint;
         }
       }
-      if (this._coalesce && xevents.coalesce[eventName]) {
-        this._enqueueCoalesced(eventName, ntkev);
-        return;
+      // a wheel is a button in the core protocol; say so in the units a
+      // consumer wants. Suppressed once XI2 is delivering the same scroll as
+      // valuators, which is the whole reason to select it (see selectXI2).
+      if (eventName === 'mousedown' && WHEEL_BUTTONS[ev.keycode] && !this._xi2?.smooth) {
+        const [deltaX, deltaY] = WHEEL_BUTTONS[ev.keycode];
+        this._deliverEvent('wheel', wheelEvent({ ...ntkev }, deltaX, deltaY, 'button'));
       }
       // the window manager reporting what it did with the window: a user who
       // hit maximize or a fullscreen hotkey changes the state behind the
@@ -673,19 +702,7 @@ export default class Window extends Drawable {
           () => {}
         );
       }
-      // deliver buffered state events before a discrete one so handlers see
-      // them in the order they happened (a drag sees the move, then the up)
-      this._flushCoalesced();
-      if (eventName === 'resize') this._tagResize(ntkev);
-      this.emit(eventName, ntkev);
-      // a WM_DELETE_WINDOW ClientMessage is the window manager *asking*, and
-      // 'close' is that question in a form an application can answer
-      if (eventName === 'message') {
-        this._emitCloseRequest(ntkev);
-        this._handleSyncRequest(ntkev);
-      }
-      // anything drawn during the handlers becomes visible in one blit
-      if (this._dirty) this._present();
+      this._deliverEvent(eventName, ntkev);
     });
 
     // Events about a *child* of this window: the substructure requests a
@@ -1169,6 +1186,32 @@ export default class Window extends Drawable {
     this._armTimer();
   }
 
+  /**
+   * Deliver one named event: buffer it if its kind coalesces, and otherwise
+   * flush what is buffered before emitting, so handlers see events in the
+   * order they happened (a drag sees the move, then the up).
+   *
+   * Every source ends here — the core event stream, the XI2 one, and the
+   * `wheel` both of them derive.
+   */
+  _deliverEvent(name, ev) {
+    if (this._coalesce && xevents.coalesce[name]) {
+      this._enqueueCoalesced(name, ev);
+      return;
+    }
+    this._flushCoalesced();
+    if (name === 'resize') this._tagResize(ev);
+    this.emit(name, ev);
+    // a WM_DELETE_WINDOW ClientMessage is the window manager *asking*, and
+    // 'close' is that question in a form an application can answer
+    if (name === 'message') {
+      this._emitCloseRequest(ev);
+      this._handleSyncRequest(ev);
+    }
+    // anything drawn during the handlers becomes visible in one blit
+    if (this._dirty) this._present();
+  }
+
   _enqueueCoalesced(name, ev) {
     const pending = this._frame.pending;
     const prev = pending.get(name);
@@ -1178,6 +1221,21 @@ export default class Window extends Drawable {
         ev.rects = [{ x: ev.x, y: ev.y, width: ev.width, height: ev.height }];
       }
       pending.set(name, ev);
+    } else if (xevents.coalesce[name] === 'accumulate') {
+      // scroll distance adds up, and the frame's scroll happened wherever the
+      // pointer ended up. The first event of the frame carries the sum, the
+      // way the union path grows its first event's rectangle.
+      prev.coalesced.push(ev);
+      prev.deltaX += ev.deltaX;
+      prev.deltaY += ev.deltaY;
+      prev.x = ev.x;
+      prev.y = ev.y;
+      prev.rootx = ev.rootx;
+      prev.rooty = ev.rooty;
+      prev.time = ev.time;
+      prev.buttons = ev.buttons;
+      prev.smooth = ev.smooth;
+      prev.source = ev.source;
     } else if (xevents.coalesce[name] === 'union') {
       prev.coalesced.push(ev);
       prev.rects.push({ x: ev.x, y: ev.y, width: ev.width, height: ev.height });
@@ -1285,6 +1343,163 @@ export default class Window extends Drawable {
     this._geSinkOpcode = sink ? majorOpcode : 0;
   }
 
+  /**
+   * Ask for XI2 device events on this window, and deliver them as the events
+   * ntk already has names for.
+   *
+   * What this buys is the wheel: the core protocol reports a scroll as a
+   * click of button 4/5/6/7, so a touchpad's two-finger gesture arrives as
+   * whole notches however finely the hardware measured it. XI2 carries the
+   * same gesture as a scroll *valuator*, and `wheel` then reports fractions
+   * of a notch (see docs/window.md "Wheel and smooth scrolling"). Touch and
+   * per-device input come with it — `ev.deviceId`/`ev.sourceId` are on every
+   * translated event, and the core protocol has no way to say either.
+   *
+   * Opt-in per window, via `createWindow({ xi2: true })` or this call,
+   * because selecting XI2 changes what the server sends: a window that has
+   * not asked keeps costing exactly what it did before.
+   *
+   * **Selecting XI2 replaces the core events of the same types.** The server
+   * delivers an event to a client once, and an XI2 selection wins, so
+   * `selectXI2(['Motion'])` means this window's `mousemove` is built from
+   * `XIMotion` from then on. It carries the same fields (plus `ev.xi2`,
+   * the device ids and sub-pixel `preciseX`/`preciseY`), so handlers do not
+   * change — but a window that selects XI2 KeyPress and nothing else still
+   * gets core motion, and mixing the two per-type is what the `types`
+   * argument is for.
+   *
+   * The emulated wheel buttons are dropped once the valuators are flowing:
+   * the server sends both halves of a smooth scroll (the axis and a button
+   * 4-7 click flagged `PointerEmulated`) so that clients which cannot read
+   * valuators still scroll, and delivering both would count every notch
+   * twice. So an app that opts in reads `wheel`, not `mousedown` on button 4.
+   *
+   * @param {string[]|string} [types] XI2 event type names —
+   *   `Motion`, `ButtonPress`, `ButtonRelease`, `KeyPress`, `KeyRelease`,
+   *   `TouchBegin`, `TouchUpdate`, `TouchEnd`. An empty array deselects.
+   * @param {{deviceId?: number}} [options] which device to select for,
+   *   defaulting to every master device (the virtual pointer and keyboard
+   *   the user is actually driving). A selection is per device, so a
+   *   selection on one device id does not replace one made on another.
+   * @returns {Promise<boolean>} false where the server has no XI2 — in which
+   *   case nothing changed and the window keeps its core events, `wheel`
+   *   included, at notch granularity
+   */
+  selectXI2(types = DEFAULT_XI2_EVENTS, { deviceId } = {}) {
+    const names = normalizeXI2Types(types);
+    return Promise.all([this.app.xinput(), this.app.inputDevices()]).then(([XI, devices]) => {
+      if (!XI || !XI.xi2 || this._destroyed) return false;
+      const target = deviceId ?? XI.AllMasterDevices;
+      if (!names.length) {
+        safeRelease(this.X, () => XI.XISelectEvents(this.id, { deviceId: target, mask: 0 }));
+        this._geHandlers.delete(XI.majorOpcode);
+        this._xi2 = null;
+        return true;
+      }
+      // DeviceChanged rides along uninvited: it is the only announcement that
+      // a master pointer's valuators are now some other slave's, which
+      // invalidates both the axis map and the accumulators built on it. Its
+      // body is undecoded, and the device id is all this needs from it.
+      safeRelease(this.X, () =>
+        XI.XISelectEvents(this.id, { deviceId: target, mask: [...names, 'DeviceChanged'] })
+      );
+      this._xi2 = {
+        ext: XI,
+        deviceId: target,
+        types: names,
+        // evtype -> the ntk event it becomes, resolved through the extension's
+        // own table rather than hardcoded numbers
+        byType: new Map(names.map((name) => [XI.EventType[name], xi2EventName[name]])),
+        scroll: this._xi2?.scroll ?? new ScrollTracker(),
+        axes: new Map(devices.map((device) => [device.deviceId, scrollAxes(device)])),
+        // whether the core wheel buttons are now redundant: a scroll-capable
+        // device plus a selection that carries its valuators
+        smooth: names.includes('Motion') && devices.some((device) => scrollAxes(device).size > 0)
+      };
+      this._geHandlers.set(XI.majorOpcode, (ev) => this._handleXI2Event(ev));
+      return true;
+    });
+  }
+
+  /**
+   * One XI2 Generic Event: scroll valuators become `wheel`, everything else
+   * becomes the core-shaped event it stands in for.
+   */
+  _handleXI2Event(ev) {
+    const xi2 = this._xi2;
+    if (!xi2) return;
+    if (ev.evtype === xi2.ext.EventType.DeviceChanged) {
+      this._refreshXI2Devices(ev.deviceId);
+      return;
+    }
+    const name = xi2.byType.get(ev.evtype);
+    if (!name) return;
+
+    const base = toNtkEvent(name, ev);
+    base.window = this;
+    base.target = this;
+
+    if (name === 'mousemove') {
+      // a scroll is a Motion carrying scroll axes; the pointer itself did not
+      // move, so it is a wheel event and not also a mouse move — including
+      // the first one, which has nothing to subtract from yet
+      const scroll = xi2.scroll.delta(ev, this._xi2Axes(ev));
+      if (scroll) {
+        if (scroll.moved) {
+          this._deliverEvent('wheel', wheelEvent(base, scroll.deltaX, scroll.deltaY, 'valuator'));
+        }
+        return;
+      }
+    }
+    if (name === 'mousedown' || name === 'mouseup') {
+      const wheelButton = WHEEL_BUTTONS[ev.detail];
+      // the click the server emulated for clients that cannot read valuators
+      // — we can, and the valuator half of the same scroll is already on its
+      // way, so this one is noise
+      if (wheelButton && ev.flags & POINTER_EMULATED) return;
+      if (wheelButton && name === 'mousedown') {
+        const wheel = wheelEvent({ ...base }, wheelButton[0], wheelButton[1], 'button');
+        this._deliverEvent('wheel', wheel);
+      }
+    }
+    if (name === 'keydown' || name === 'keyup') {
+      const key = decodeKey(this.X.keycode2keysyms[ev.detail], base.buttons);
+      if (key) {
+        base.keysym = key.keysym;
+        base.baseKeysym = key.baseKeysym;
+        base.group = key.group;
+        if (key.codepoint !== undefined) base.codepoint = key.codepoint;
+      }
+    }
+    this._deliverEvent(name, base);
+  }
+
+  /** This window's scroll-axis map for the device an event came from. */
+  _xi2Axes(ev) {
+    return this._xi2?.axes.get(ev.deviceId);
+  }
+
+  /**
+   * A master device's slave changed: re-read what its axes are now, and drop
+   * the accumulators, because the values arriving next belong to a different
+   * device and subtracting across the switch is the jump seeding exists to
+   * avoid.
+   */
+  _refreshXI2Devices(deviceId) {
+    const xi2 = this._xi2;
+    if (!xi2) return;
+    xi2.scroll.reset(deviceId);
+    this.app.inputDevices({ refresh: true }).then(
+      (devices) => {
+        if (this._xi2 !== xi2) return; // deselected or reselected meanwhile
+        xi2.axes = new Map(devices.map((device) => [device.deviceId, scrollAxes(device)]));
+        xi2.smooth =
+          xi2.types.includes('Motion') && devices.some((device) => scrollAxes(device).size > 0);
+      },
+      () => {}
+    );
+  }
+
   /**
    * Present's events, which are the ones the core event table cannot name:
    * they arrive as X Generic Events (type 35), carrying an extension opcode
@@ -1703,6 +1918,7 @@ export default class Window extends Drawable {
       safeRelease(X, () => fixes.CreateRegion(this._updateRegion, []));
       this._presentExt = present;
       this._fixesExt = fixes;
+      this._geHandlers.set(present.majorOpcode, (ev) => this._handlePresentEvent(ev));
       this._selectPresentInput();
       return this;
     });

package/lib/xi2.js

@@ -0,0 +1,290 @@
+/**
+ * XI2 (X Input Extension 2) device events: what to select, how to turn one
+ * into an ntk event, and the per-device bookkeeping a scroll delta needs.
+ *
+ * The core protocol flattens every input device onto one virtual pointer and
+ * one virtual keyboard, and reports a wheel as a click of button 4/5/6/7. A
+ * touchpad's two-finger scroll therefore reaches a core client as a series of
+ * whole notches, which is why nothing built on core X can scroll smoothly.
+ * XI2 carries the same gesture as a *valuator*: an absolute accumulator per
+ * scroll axis, whose difference between two events is the distance scrolled,
+ * in units of the axis' `increment` (one notch).
+ *
+ * Three facts shape everything here:
+ *
+ * 1. **Valuators are absolute.** A delta is `(now - before) / increment`, so
+ *    the first event from a device has nothing to subtract from and must seed
+ *    rather than report — otherwise the first scroll of a session jumps by
+ *    however far the axis had travelled before the window existed.
+ * 2. **A device's axes are described once, not per event.** Which valuator is
+ *    the vertical scroll axis, and what one notch of it is worth, comes from
+ *    `XIQueryDevice`'s `Scroll` classes. They change under a master device
+ *    when the user switches from a mouse to a touchpad, which is what
+ *    `XIDeviceChanged` announces — and that also resets the accumulators.
+ * 3. **Selecting XI2 turns off core delivery.** The server delivers an event
+ *    to a client once: an XI2 selection on a window suppresses the core
+ *    events of the same types *for that client on that window*. So a window
+ *    that selects XI2 Motion stops receiving core MotionNotify, and this
+ *    module has to reproduce the core-shaped event ntk consumers already
+ *    listen for.
+ */
+
+/**
+ * XI2 event types ntk can deliver, and the ntk event each becomes.
+ *
+ * Only the types node-x11 decodes into fields are here. The rest —
+ * Enter/Leave, FocusIn/FocusOut, HierarchyChanged, the barriers — arrive with
+ * their bodies undecoded (`ev.data`), and selecting one would suppress the
+ * core event that *is* decoded in exchange for nothing.
+ */
+export const xi2EventName = {
+  Motion: 'mousemove',
+  ButtonPress: 'mousedown',
+  ButtonRelease: 'mouseup',
+  KeyPress: 'keydown',
+  KeyRelease: 'keyup',
+  TouchBegin: 'touchstart',
+  TouchUpdate: 'touchmove',
+  TouchEnd: 'touchend'
+};
+
+/**
+ * What `xi2: true` selects: the pointer, which is what smooth scrolling
+ * needs. Keyboard and touch are opt-in by name — a window that selects XI2
+ * KeyPress takes on decoding it (and loses the core KeyPress it was getting).
+ */
+export const DEFAULT_XI2_EVENTS = ['Motion', 'ButtonPress', 'ButtonRelease'];
+
+// XIScrollClass.scrollType
+const SCROLL_VERTICAL = 1;
+
+// XIPointerEventFlags.PointerEmulated: this button event is the server's
+// rendering of a scroll axis into a wheel click, for clients that cannot read
+// valuators. Both halves of the scroll are sent, so a client that reads the
+// axis has to drop this one or count every notch twice.
+export const POINTER_EMULATED = 1 << 16;
+
+/** Wheel buttons in the core protocol: up, down, left, right. */
+export const WHEEL_BUTTONS = { 4: [0, -1], 5: [0, 1], 6: [-1, 0], 7: [1, 0] };
+
+/**
+ * Check a list of XI2 event-type names, and say what a caller can ask for.
+ *
+ * The failure this catches is a silent one: an unknown name reaches
+ * `XISelectEvents` as `undefined` and throws from node-x11 naming a bit
+ * position, and a *known* name ntk cannot decode (`Enter`) would select
+ * happily and then deliver nothing anyone can read.
+ *
+ * @param {string[]|string} types
+ * @returns {string[]}
+ */
+export function normalizeXI2Types(types) {
+  const list = typeof types === 'string' ? [types] : Array.from(types ?? []);
+  for (const name of list) {
+    if (xi2EventName[name]) continue;
+    const known = Object.keys(xi2EventName).join(', ');
+    throw new Error(
+      `ntk: selectXI2 cannot deliver '${name}'. Supported XI2 event types: ${known}. ` +
+        (name?.startsWith?.('Raw')
+          ? 'Raw events carry no window and are only sent for selections on the root, ' +
+            'so they are not routed to a window — read them off app.X directly.'
+          : 'Other XI2 events arrive with their bodies undecoded, and selecting one ' +
+            'would suppress the core event carrying the same information.')
+    );
+  }
+  return list;
+}
+
+/**
+ * The scroll axes of one device, from its `XIQueryDevice` classes:
+ * valuator number -> `{ vertical, increment }`.
+ *
+ * A device with no scroll class (a plain wheel mouse on an old driver, a
+ * tablet) yields an empty map, and everything below then leaves scrolling to
+ * the emulated buttons.
+ */
+export function scrollAxes(device) {
+  const axes = new Map();
+  for (const cls of device?.classes ?? []) {
+    // ClassType.Scroll
+    if (cls.type !== 3) continue;
+    if (!cls.increment) continue; // an axis one of whose notches is 0 long
+    axes.set(cls.number, {
+      vertical: cls.scrollType === SCROLL_VERTICAL,
+      increment: cls.increment
+    });
+  }
+  return axes;
+}
+
+/**
+ * Per-device scroll accumulators.
+ *
+ * Keyed by the *source* device as well as the master, because a master
+ * pointer's valuators are whatever its last-used slave put there: switching
+ * from the touchpad to the mouse continues the numbering with an unrelated
+ * value, and subtracting across that switch is the same jump as subtracting
+ * from zero.
+ */
+export class ScrollTracker {
+  constructor() {
+    this._last = new Map();
+  }
+
+  /** Forget a device's axes: the next event from it seeds again. */
+  reset(deviceId) {
+    for (const key of this._last.keys()) {
+      if (key.startsWith(`${deviceId}:`)) this._last.delete(key);
+    }
+  }
+
+  /**
+   * The scroll an event's valuators describe, or null when it carries no
+   * scroll axis and is therefore about something else (a pointer move).
+   *
+   * `moved` distinguishes a scroll from the first event of one: the seeding
+   * event carries a scroll axis — so it is not a pointer move and must not be
+   * reported as one — but has nothing to subtract from and so no distance to
+   * report. Distances are in notches, fractional, positive down and right
+   * (the direction a DOM `wheel` event calls positive).
+   *
+   * @param {object} ev a decoded XI2 device event
+   * @param {Map<number, {vertical: boolean, increment: number}>} axes
+   * @returns {{deltaX: number, deltaY: number, moved: boolean}|null}
+   */
+  delta(ev, axes) {
+    if (!axes?.size) return null;
+    let deltaX = 0;
+    let deltaY = 0;
+    let scrolled = false;
+    let moved = false;
+    for (const [number, axis] of axes) {
+      const value = ev.valuators?.[number];
+      if (value === undefined) continue;
+      scrolled = true;
+      const key = `${ev.deviceId}:${ev.sourceId}:${number}`;
+      const previous = this._last.get(key);
+      this._last.set(key, value);
+      // seeding: an absolute accumulator says nothing on its own
+      if (previous === undefined || value === previous) continue;
+      moved = true;
+      // a negative increment is how a device declares its axis inverted, and
+      // dividing by it puts the delta back in the natural direction
+      const notches = (value - previous) / axis.increment;
+      if (axis.vertical) deltaY += notches;
+      else deltaX += notches;
+    }
+    return scrolled ? { deltaX, deltaY, moved } : null;
+  }
+}
+
+/**
+ * The core `state` field, rebuilt from an XI2 event.
+ *
+ * ntk hands this to consumers as `ev.buttons` and to the keyboard decoder as
+ * the layout group, both of which predate XI2 and read the core bit layout:
+ * modifiers in bits 0-7, buttons 1-5 in bits 8-12, the XKB group in 13-14.
+ * XI2 splits the same information three ways, and reports buttons as a list.
+ */
+export function coreState(ev) {
+  let state = (ev.mods?.effective ?? 0) & 0xff;
+  for (const button of ev.buttons ?? []) {
+    if (button >= 1 && button <= 5) state |= 1 << (7 + button);
+  }
+  state |= ((ev.group?.effective ?? 0) & 3) << 13;
+  return state;
+}
+
+// Core event codes, so a translated event answers `ev.type` the way the event
+// it stands in for would.
+const coreType = {
+  mousemove: 6,
+  mousedown: 4,
+  mouseup: 5,
+  keydown: 2,
+  keyup: 3
+};
+
+/**
+ * An XI2 device event in the shape ntk delivers.
+ *
+ * Core-compatible where the two overlap — a handler written against
+ * `mousedown` cannot tell the difference — with the XI2 extras alongside:
+ * `deviceId`/`sourceId`, the sub-pixel `preciseX`/`preciseY` that FP1616
+ * coordinates carry and the integer `x`/`y` cannot, and the raw `valuators`.
+ */
+export function toNtkEvent(name, ev) {
+  const out = {
+    type: coreType[name] ?? ev.type,
+    name: ev.name,
+    xi2: true,
+    time: ev.time,
+    root: ev.root,
+    wid: ev.wid,
+    child: ev.child,
+    // core X reports integer coordinates; keep that the delivered contract and
+    // put the precision XI2 adds next to it rather than in place of it
+    x: Math.round(ev.x),
+    y: Math.round(ev.y),
+    rootx: Math.round(ev.rootx),
+    rooty: Math.round(ev.rooty),
+    preciseX: ev.x,
+    preciseY: ev.y,
+    preciseRootX: ev.rootx,
+    preciseRootY: ev.rooty,
+    buttons: coreState(ev),
+    buttonsDown: ev.buttons,
+    deviceId: ev.deviceId,
+    sourceId: ev.sourceId,
+    flags: ev.flags,
+    valuators: ev.valuators,
+    sameScreen: 1
+  };
+  // `detail` is the keycode, the button number or the touch id, depending;
+  // core X calls the first two `keycode`, and ntk documents them under that
+  if (name === 'touchstart' || name === 'touchmove' || name === 'touchend') {
+    out.touchId = ev.detail;
+  } else {
+    out.keycode = ev.detail;
+  }
+  return out;
+}
+
+/**
+ * A `wheel` event: `deltaX`/`deltaY` in notches, positive down and right.
+ *
+ * Notches rather than pixels, because a notch is the only unit the device
+ * agrees on — `increment` is defined as the value that makes one — and how
+ * many pixels one is worth is the consumer's line height, not ours. A
+ * touchpad reports fractions of one, which is the whole point: `smooth` says
+ * whether this delta came from a device that can, so a consumer can decide
+ * whether to animate the scroll or snap it.
+ *
+ * @param {string} source 'valuator' (XI2 scroll axes) or 'button' (4-7)
+ */
+export function wheelEvent(base, deltaX, deltaY, source) {
+  return {
+    // `type` stays that of the X event this was derived from — a button press
+    // or a motion — because a wheel has no core event code of its own
+    ...base,
+    name: 'wheel',
+    deltaX,
+    deltaY,
+    deltaMode: 'line',
+    smooth: source === 'valuator',
+    source
+  };
+}
+
+export default {
+  xi2EventName,
+  DEFAULT_XI2_EVENTS,
+  POINTER_EMULATED,
+  WHEEL_BUTTONS,
+  normalizeXI2Types,
+  scrollAxes,
+  ScrollTracker,
+  coreState,
+  toNtkEvent,
+  wheelEvent
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "7.4.0",
+  "version": "7.6.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",