ntk 8.2.0 → 8.3.1

package/lib/app.js

@@ -1,14 +1,19 @@
+import { connectionGone } from './cleanup.js';
 import Clipboard from './clipboard.js';
 import { CursorCache } from './cursor.js';
 import { GLError, backendFor, glCapabilities, glError, resolveGLPolicy } from './gl.js';
 import { chooseGLXConfig } from './glx.js';
 import Picture from './picture.js';
 import Pixmap from './pixmap.js';
+import Region, { REGION_DOCS } from './region.js';
+import { formatForDepth, parsePictFormats, visualDepths, visualFormats } from './pictformat.js';
 import { DEFAULT_RASTER_POLICY, defaultRasterizer } from './rasterize.js';
 import { dropShadowSurfaces } from './shadow.js';
+import { sharedGlyphsFor } from './sharedglyphs.js';
 import { ShmUploader } from './shm-upload.js';
 import FontManager from './text/fontmanager.js';
 import Window from './window.js';
+import * as xevents from './events_map.js';
 
 /**
  * The highest predefined atom id in the core protocol, `XA_WM_TRANSIENT_FOR`.
@@ -54,6 +59,38 @@ function modeRate(mode) {
   return mode.dot_clock / (mode.h_total * vTotal);
 }
 
+/**
+ * XFIXES is missing, so no server-side regions.
+ *
+ * Worth a sentence about who is likely reading it: every X.Org release since
+ * 2004 and every XQuartz ship XFIXES, so a server without it is a deliberately
+ * minimal one — an embedded/nested server, or node-x11's own pure-JS server,
+ * which implements RENDER but not this. That is a fact about the display, not
+ * about the call, which is why it carries a `code`: a host that can degrade
+ * should branch on it rather than crash.
+ *
+ * @param {Error} [cause] whatever the extension query failed with
+ */
+function noXFixesError(cause) {
+  const err = new Error(
+    'ntk: the X server has no XFIXES extension, so it has no regions.\n' +
+      '\n' +
+      'Region clips (ctx.clipRegion), damage regions and window shapes all need it.\n' +
+      'Rectangular and path clips do not — ctx.clip() is core RENDER and works\n' +
+      'everywhere:\n' +
+      '\n' +
+      '    ctx.save();\n' +
+      '    ctx.beginPath();\n' +
+      '    ctx.rect(x, y, w, h);\n' +
+      '    ctx.clip();\n' +
+      '\n' +
+      `${REGION_DOCS}`,
+    cause ? { cause } : undefined
+  );
+  err.code = 'ERR_NTK_NO_XFIXES';
+  return err;
+}
+
 /**
  * A connection to an X server. Owns the underlying node-x11 client
  * (`app.X`) and acts as a factory for windows and pixmaps.
@@ -90,12 +127,34 @@ export default class App {
     this._isolateAtoms();
     this._fonts = null;
     this._clipboard = null;
+    // Decide the shared-glyph question now, while the environment the app
+    // was created under is what the caller sees: the kill switch and the
+    // option are sampled once per connection, not per page. Constructing the
+    // client costs no I/O — discovery waits for the first page to bind.
+    sharedGlyphsFor(this);
     this._cursors = null;
     this._solidPictures = new Map();
     this._rasterizer = undefined;
     this._shm = undefined;
-    this._xinputPromise = null;
+    this._extensionPromises = new Map();
+    // extension event routing (see _routeExtensionEvents): server-assigned
+    // event type code -> events_map.extension entry. Null until the first
+    // extension with events is required, which is also when the client-level
+    // listener that consults it is attached.
+    this._extEvents = null;
     this._devicesPromise = null;
+    // XFIXES, once something has asked for it (regions, `app.fixes()`). The
+    // promise lives in _extensionPromises with the other extensions; the
+    // resolved object is also kept here because a region clip has to be
+    // installed synchronously, in request order with the drawing around it —
+    // see RenderingContext2d#clipRegion.
+    this._fixes = null;
+    // The visual -> picture format table and the formats list it was built
+    // from, read once out of node-x11's cached QueryPictFormats reply. Kept
+    // resolved alongside the promise so that binding a picture, which happens
+    // synchronously, can consult it without waiting (see pictFormats).
+    this._pictFormats = null;
+    this._pictFormatsPromise = 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
@@ -195,6 +254,12 @@ export default class App {
   _probeRefreshRate() {
     this._refreshProbe = null; // in progress; only ever started once
     const X = this.X;
+    // A connection on its way out is one more "no rate to be had". The probe
+    // is started lazily by the first window built on this connection, which
+    // may be one adopted from an event still arriving as it closes — and
+    // node-x11 throws synchronously at a request from then on, where the
+    // event dispatch has no caller to catch it (issue #321).
+    if (connectionGone(X)) return;
     X.require('randr', (err, R) => {
       if (err || !R) return;
       const root = this.display.screen[0].root;
@@ -302,6 +367,89 @@ export default class App {
     });
   }
 
+  /**
+   * The node-x11 object for extension `name`, or `null` where the server has
+   * none — asked once per connection, the absent answer included.
+   *
+   * node-x11 caches the `QueryExtension` reply itself since 4.0.1
+   * ([node-x11#287](https://github.com/sidorares/node-x11/issues/287)), so a
+   * repeated probe no longer costs a round trip even when the answer is
+   * absent — "can this machine run a compositor?" is a question about what is
+   * *not* there, and it used to pay for asking. This cache stays for what it
+   * does beyond that: one promise per name, so concurrent callers share the
+   * one query, `_routeExtensionEvents` runs once rather than per call, and an
+   * absent extension answers `null` instead of an error.
+   *
+   * `name` is node-x11's module name (`'fixes'`, not `'XFIXES'`), and the
+   * accessors below are the whole supported set. Deliberately not public: a
+   * name that arrives misspelled resolves `null` forever, which is
+   * indistinguishable from a server that does not have the extension.
+   *
+   * @param {string} name
+   * @returns {Promise<object|null>}
+   */
+  _extension(name) {
+    let pending = this._extensionPromises.get(name);
+    if (!pending) {
+      pending = new Promise((resolve) => {
+        this.X.require(name, (err, ext) => {
+          if (!err && ext) this._routeExtensionEvents(name, ext);
+          resolve(err ? null : ext);
+        });
+      });
+      this._extensionPromises.set(name, pending);
+    }
+    return pending;
+  }
+
+  /**
+   * Give this extension's events names, and a route to the object they name.
+   *
+   * A non-generic extension event carries a server-assigned type code
+   * (`firstEvent` + a fixed offset) and names its target under the field its
+   * own protocol calls it — DamageNotify a `drawable`, ShapeNotify and the
+   * XFIXES notifies a `window` — never under the `wid` node-x11 dispatches
+   * per-window consumers by. So without this they reach the client's raw
+   * `'event'` stream and nothing else (issue #290).
+   *
+   * Registered here, when the extension is first required through the
+   * accessors above, because the type codes exist only once the server has
+   * answered. From then on the listener below hands each one to the Window
+   * or Pixmap it names — through `_deliverEvent`, so a window's coalescing
+   * and frame pacing apply: `damage` unions its rectangles per paced frame
+   * exactly as `expose` does. The lookup goes through `X.event_consumers`,
+   * where every Window already sits for core dispatch and a Pixmap enrols
+   * itself when given a listener (see lib/pixmap.js).
+   */
+  _routeExtensionEvents(module, ext) {
+    const events = xevents.extension[module];
+    if (!events || !ext.firstEvent || !ext.events) return;
+    if (!this._extEvents) {
+      this._extEvents = new Map();
+      this.X.on('event', (ev) => {
+        // by the server-assigned type code, which every extension event
+        // carries since x11 4.0.0 (node-x11#284 — DamageNotify and a couple
+        // of others used to name themselves without it). Only the codes this
+        // table registered can match.
+        const route = this._extEvents.get(ev.type);
+        if (!route) return;
+        const target = this.X.event_consumers[ev[route.target]];
+        // a consumer that is not an ntk drawable (a caller's own) keeps
+        // reading the raw client stream it always read
+        if (typeof target?._deliverEvent !== 'function') return;
+        const ntkev = route.translate(ev);
+        ntkev.target = target;
+        if (target instanceof Window) ntkev.window = target;
+        target._deliverEvent(route.name, ntkev);
+      });
+    }
+    for (const [key, spec] of Object.entries(events)) {
+      const offset = ext.events[key];
+      if (offset === undefined) continue;
+      this._extEvents.set(ext.firstEvent + offset, spec);
+    }
+  }
+
   /**
    * The XInput extension, or `null` where the server has none — asked once
    * per connection.
@@ -312,12 +460,59 @@ export default class App {
    * @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;
+    return this._extension('xinput');
+  }
+
+  /**
+   * The Composite extension, or `null` where the server has none: the
+   * redirection half of a compositing manager — `RedirectSubwindows`,
+   * `NameWindowPixmap`, `Get`/`ReleaseOverlayWindow`
+   * (docs/app.md#extensions).
+   *
+   * `null` here is a live answer rather than a defensive one, and the one
+   * worth branching on: XQuartz carries DAMAGE, XFIXES, SHAPE and RENDER but
+   * no Composite at all, so this is where "can this machine run a
+   * compositor?" is decided.
+   *
+   * @returns {Promise<object|null>}
+   */
+  composite() {
+    return this._extension('composite');
+  }
+
+  /**
+   * The DAMAGE extension, or `null` where the server has none: what turns
+   * "this drawable changed" into an event, so a compositor repaints the
+   * region a client drew into rather than the screen
+   * (docs/app.md#extensions).
+   *
+   * @returns {Promise<object|null>}
+   */
+  damage() {
+    return this._extension('damage');
+  }
+
+  /**
+   * The XFIXES extension, or `null` where the server has none: server-side
+   * regions and the algebra over them, which is how a damaged area becomes a
+   * clip — `SetPictureClipRegion(ctx.picture.id, 0, 0, region)` narrows a 2d
+   * context to one (docs/app.md#extensions).
+   *
+   * @returns {Promise<object|null>}
+   */
+  xfixes() {
+    return this._extension('fixes');
+  }
+
+  /**
+   * The SHAPE extension, or `null` where the server has none: non-rectangular
+   * window bounding/clip/input shapes, which a compositor has to read to
+   * paint a shaped client correctly (docs/app.md#extensions).
+   *
+   * @returns {Promise<object|null>}
+   */
+  shape() {
+    return this._extension('shape');
   }
 
   /**
@@ -355,6 +550,18 @@ export default class App {
     return this._clipboard;
   }
 
+  /**
+   * The cross-process shared glyph cache client (docs/shared-glyphs.md), or
+   * `null` when the feature is off — `createClient({ sharedGlyphs: false })`
+   * or the `NTK_NO_SHARED_GLYPHS` environment kill switch. Purely lazy: the
+   * accessor itself touches no server state; discovery (and the first app's
+   * self-election as the display's glyph directory) happens when the first
+   * glyph page binds.
+   */
+  get sharedGlyphs() {
+    return sharedGlyphsFor(this);
+  }
+
   /** per-connection cache of X11 cursor-font cursors (see lib/cursor.js) */
   get cursors() {
     if (!this._cursors) this._cursors = new CursorCache(this);
@@ -456,6 +663,102 @@ export default class App {
     return null;
   }
 
+  /**
+   * The RENDER picture formats this server publishes, and which one belongs
+   * to each visual: `{ formats, byVisual }`.
+   *
+   * No round trip of ntk's own: node-x11 sends `QueryPictFormats` itself
+   * while requiring RENDER — that is where its `rgb24`/`rgba32`/`a8` come
+   * from — and since 4.0.0 it keeps the reply as `Render.pictFormats`. So
+   * the answer is already here before anything can draw. `formats` is the
+   * list as objects (`{ id, type, depth, redShift, redMask, ... }`);
+   * `byVisual` is a `Map` from visual id to format id.
+   *
+   * @returns {Promise<{formats: Array<object>, byVisual: Map<number, number>}>}
+   */
+  pictFormats() {
+    if (this._pictFormatsPromise) return this._pictFormatsPromise;
+    this._pictFormatsPromise = new Promise((resolve, reject) => {
+      const reply = this.display.Render?.pictFormats;
+      if (!reply) {
+        reject(new Error('ntk: this connection has no RENDER extension, so it has no picture formats'));
+        return;
+      }
+      const formats = parsePictFormats(reply);
+      this._pictFormats = {
+        formats,
+        byVisual: visualFormats(this.display, formats, reply)
+      };
+      resolve(this._pictFormats);
+    });
+    return this._pictFormatsPromise;
+  }
+
+  /**
+   * The picture format a drawable on `visual` is read and written through.
+   *
+   * Depth is not enough to name a format and a visual is: a depth-16 visual
+   * can be 5:6:5 or 5:5:5, a depth-24 one RGB or BGR, and 10:10:10:2 is 32
+   * bits wide like 8:8:8:8. Anything drawing on a drawable it did not create
+   * — a compositor holding another client's pixmap, an adopted or embedded
+   * window — has to ask, or RENDER reads the channels wrong without ever
+   * complaining (issue #295).
+   *
+   *   const attrs = await wnd.getAttributes();
+   *   const format = await app.pictFormatFor(attrs.visual);
+   *
+   * `visual` may be an id or a handshake visual object. `depth` is the
+   * fallback: where the server names no format for the visual — an indexed
+   * visual, or one this connection was never told about — the standard
+   * format for that depth is returned, which is what ntk used to assume
+   * everywhere.
+   *
+   * @param {number|object} visual visual id, or `{ vid }`
+   * @param {object} [options]
+   * @param {number} [options.depth] the drawable's depth, for the fallback
+   * @returns {Promise<number|undefined>} picture format id
+   */
+  async pictFormatFor(visual, { depth } = {}) {
+    const id = typeof visual === 'object' && visual ? visual.vid : visual;
+    try {
+      await this.pictFormats();
+    } catch {
+      // a server that cannot answer leaves the fallback
+    }
+    return this._knownPictFormat(id, depth) ?? formatForDepth(this.display.Render, depth);
+  }
+
+  /**
+   * The cached answer to `pictFormatFor`, or `undefined` when the table has
+   * not arrived, names no format for this visual, or the visual does not
+   * describe a drawable of this depth.
+   *
+   * That last one is the guard against handing RENDER a format it will
+   * reject: a picture's format and its drawable's depth have to agree, and
+   * the visual on hand is not always the drawable's own — a window's backing
+   * pixmap is allocated at a depth ntk sometimes has to assume. Where they
+   * disagree the depth is what the drawable really is, so the depth-based
+   * format is what it gets.
+   *
+   * A picture is bound synchronously, in request order with the drawing
+   * around it, so the format has to be available without a wait. Callers
+   * fall back to the depth and re-bind once `pictFormats()` resolves.
+   */
+  _knownPictFormat(visual, depth) {
+    if (!visual) return undefined;
+    const id = visual >>> 0;
+    const format = this._pictFormats?.byVisual.get(id);
+    if (format === undefined) return undefined;
+    // Depth 0 is not a depth: it is CopyFromParent, which ntk never resolved
+    // because only the server did — and a window on that visual is of that
+    // visual's depth by definition, so there is nothing to disagree with.
+    if (depth) {
+      this._visualDepths ??= visualDepths(this.display);
+      if (this._visualDepths.get(id) !== depth) return undefined;
+    }
+    return format;
+  }
+
   rootWindow(screen = 0) {
     return new Window(this, { id: this.display.screen[screen].root });
   }
@@ -497,6 +800,42 @@ export default class App {
     return new Pixmap(this, args);
   }
 
+  /**
+   * The XFIXES extension for this connection, loaded once and shared.
+   *
+   * Regions live here — the server-side rectangle sets X uses for damage,
+   * window shapes and compositor bookkeeping — along with the requests that
+   * combine them and the one that hangs a region on a Picture as its clip.
+   *
+   * The throwing spelling of `app.xfixes()`: same query, same cache, but a
+   * server without XFIXES rejects with code `'ERR_NTK_NO_XFIXES'` instead of
+   * resolving `null` — regions cannot degrade, so their absence is an error
+   * here rather than an answer.
+   *
+   * @returns {Promise<object>} node-x11's XFIXES extension object
+   */
+  async fixes() {
+    const ext = await this.xfixes();
+    if (!ext) throw noXFixesError();
+    this._fixes = ext;
+    return ext;
+  }
+
+  /**
+   * A server-side region of the given rectangles (`{ x, y, width, height }`
+   * or ntk's own `{ x, y, w, h }`), empty by default.
+   *
+   * Async because XFIXES is loaded on first use; a second region costs one
+   * request and no round trip. Free it with `destroy()` — or `using`, or let
+   * the GC do it (docs/resource-management.md).
+   *
+   * @param {Array<object>} [rects]
+   * @returns {Promise<Region>}
+   */
+  async createRegion(rects = []) {
+    return new Region(this, await this.fixes(), rects);
+  }
+
   /**
    * A repeating source Picture of one colour, for compositing. Components
    * are 0..1 floats, premultiplied by alpha.

package/lib/cleanup.js

@@ -1,11 +1,27 @@
-// Release a server-side resource, tolerating a connection that is closing or
-// already gone — the X server frees all of a client's resources on disconnect,
-// so there is nothing left to do and nothing worth throwing about. This
-// matters for FinalizationRegistry callbacks, which run after app.close() if
-// wrappers get garbage collected late and have no user code around them to
-// catch.
+/**
+ * Whether a request issued now would throw rather than reach the server.
+ * node-x11 throws *synchronously* ("client is in closing state") once
+ * `close()` has begun, and a destroyed or ended stream is the same state one
+ * step further along.
+ *
+ * The check matters wherever a request is issued from somewhere with no
+ * caller to catch: a FinalizationRegistry callback, a paced frame's timer, or
+ * the X event dispatch itself — events already in the read buffer keep being
+ * delivered after `close()` (issue #321).
+ */
+export function connectionGone(X) {
+  return !!(X._closing || !X.stream || X.stream.destroyed || X.stream.writableEnded);
+}
+
+// Issue requests — typically releasing a server-side resource — tolerating a
+// connection that is closing or already gone. The X server frees all of a
+// client's resources on disconnect, so there is nothing left to do and
+// nothing worth throwing about. This matters wherever the requests have no
+// caller around them to catch: FinalizationRegistry callbacks, which run
+// after app.close() if wrappers get garbage collected late, a paced frame's
+// timer, and the X event dispatch (issue #321).
 export function safeRelease(X, fn) {
-  if (X._closing || !X.stream || X.stream.destroyed || X.stream.writableEnded) return;
+  if (connectionGone(X)) return;
   try {
     fn();
   } catch {

package/lib/drawable.js

@@ -11,6 +11,16 @@ export default class Drawable extends EventEmitter {
     if (!factory) throw new Error(`Unknown rendering context: ${name}`);
     return factory(this, ...args);
   }
+
+  /**
+   * Deliver one named event to this drawable's listeners. Window overrides
+   * this with per-frame coalescing and pacing; the base emits directly,
+   * for drawables with no frame clock — a Pixmap a DAMAGE object watches
+   * (see App#_routeExtensionEvents).
+   */
+  _deliverEvent(name, ev) {
+    this.emit(name, ev);
+  }
 }
 
 // populated by the renderingcontext_* modules on import

package/lib/events_map.js

@@ -86,6 +86,10 @@ export const coalesce = {
   mousemove: 'last',
   resize: 'last',
   expose: 'union',
+  // DamageNotify is the expose case again — a burst of rectangles whose
+  // union is what a repaint wants — reported about a drawable's content
+  // instead of a window's visibility
+  damage: '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
@@ -93,6 +97,101 @@ export const coalesce = {
   wheel: 'accumulate'
 };
 
+// XFixes SelectionNotify subtype -> why the ownership changed, the same
+// vocabulary clipboard.watch already answers in. The codes are fixed by
+// xfixesproto (SelectionEvent), not assigned by the server.
+const selectionReason = ['new-owner', 'destroyed', 'closed'];
+
+// ShapeNotify kind -> which of the window's three shapes changed
+// (shapeproto ShapeKind)
+const shapeKind = ['bounding', 'clip', 'input'];
+
+/**
+ * The non-generic extension events, and how to deliver them.
+ *
+ * Unlike core events their type codes are assigned by the server at
+ * QueryExtension time (`ext.firstEvent` + a fixed offset), and the drawable
+ * each one names arrives under the field its own protocol calls it —
+ * DamageNotify a `drawable`, the others a `window` — never under the `wid`
+ * node-x11 dispatches per-window consumers by. So they need both halves of
+ * this table: a name, and which field to route by. App reads it when an
+ * extension is required through its accessors (`app.damage()` and friends)
+ * and hands each event to the Window or Pixmap it names — see
+ * App#_routeExtensionEvents and docs/app.md "Extension events".
+ *
+ * Keyed by node-x11's module name, then by the event's key in `ext.events`.
+ * `translate` shapes the raw node-x11 event into the one delivered.
+ */
+export const extension = {
+  damage: {
+    DamageNotify: {
+      name: 'damage',
+      target: 'drawable',
+      // expose-shaped, because it is the same news: the box in
+      // x/y/width/height so 'union' coalescing applies to it unchanged.
+      // Bit 7 of the level byte is the wire's own "more follow" flag —
+      // split out, since the report level it rides on is 0..3.
+      translate: (ev) => ({
+        x: ev.area.x,
+        y: ev.area.y,
+        width: ev.area.w,
+        height: ev.area.h,
+        geometry: ev.geometry,
+        damage: ev.damage,
+        level: ev.level & 0x7f,
+        more: !!(ev.level & 0x80),
+        time: ev.time
+      })
+    }
+  },
+  fixes: {
+    // 'selection' is taken — it is core SelectionNotify, a conversion
+    // answered — and this event is about who owns the selection, hence the
+    // qualified name
+    SelectionNotify: {
+      name: 'selection_owner',
+      target: 'window',
+      translate: (ev) => ({
+        selection: ev.selection,
+        owner: ev.owner,
+        reason: selectionReason[ev.subtype] ?? ev.subtype,
+        timestamp: ev.timestamp,
+        selectionTimestamp: ev.selectionTimestamp
+      })
+    },
+    CursorNotify: {
+      name: 'cursor',
+      target: 'window',
+      translate: (ev) => ({
+        cursorSerial: ev.cursorSerial,
+        cursorName: ev.cursorName,
+        time: ev.timestamp
+      })
+    }
+  },
+  shape: {
+    ShapeNotify: {
+      name: 'shape',
+      target: 'window',
+      translate: (ev) => ({
+        kind: shapeKind[ev.kind] ?? ev.kind,
+        x: ev.x,
+        y: ev.y,
+        width: ev.width,
+        height: ev.height,
+        shaped: !!ev.shaped,
+        time: ev.time
+      })
+    }
+  }
+};
+
+// every routed extension event name — what a Pixmap watches `newListener`
+// for to enrol itself in the routing table (see lib/pixmap.js)
+export const extensionEventNames = new Set(
+  Object.values(extension).flatMap((events) => Object.values(events).map((spec) => spec.name))
+);
+
 export const toSnake = {
   onMouseMove: 'mousemove',
   onMouseOver: 'mouseover',
@@ -124,4 +223,4 @@ export const maskCamelCase = Object.fromEntries(
   Object.entries(toSnake).map(([camel, snake]) => [camel, mask[snake]])
 );
 
-export default { eventName, mask, maskCamelCase, toSnake, coalesce };
+export default { eventName, mask, maskCamelCase, toSnake, coalesce, extension, extensionEventNames };