ntk 3.1.0 → 3.3.0

package/lib/app.js

@@ -1,3 +1,5 @@
+import Clipboard from './clipboard.js';
+import { CursorCache } from './cursor.js';
 import Pixmap from './pixmap.js';
 import FontManager from './text/fontmanager.js';
 import Window from './window.js';
@@ -18,6 +20,8 @@ export default class App {
     this.X = display.client;
     this.options = options;
     this._fonts = null;
+    this._clipboard = null;
+    this._cursors = 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
@@ -36,6 +40,18 @@ export default class App {
     return this._fonts;
   }
 
+  /** selection/clipboard transfer: write()/read() text (docs/clipboard.md) */
+  get clipboard() {
+    if (!this._clipboard) this._clipboard = new Clipboard(this);
+    return this._clipboard;
+  }
+
+  /** per-connection cache of X11 cursor-font cursors (see lib/cursor.js) */
+  get cursors() {
+    if (!this._cursors) this._cursors = new CursorCache(this);
+    return this._cursors;
+  }
+
   createWindow(args) {
     return new Window(this, args);
   }
@@ -50,6 +66,10 @@ export default class App {
 
   // flush pending requests and close the connection
   close() {
+    if (this._cursors) {
+      this._cursors.dispose();
+      this._cursors = null;
+    }
     return new Promise((resolve) => this.X.close(resolve));
   }
 

package/lib/clipboard.js

@@ -0,0 +1,317 @@
+import x11 from 'x11';
+
+import { safeRelease } from './cleanup.js';
+
+// Clipboard (app.clipboard): ICCCM selection transfer for plain text.
+//
+// X has no clipboard buffer — "copy" means owning a selection atom
+// (CLIPBOARD for explicit copy/paste, PRIMARY for middle-click paste) and
+// answering conversion requests from whoever pastes; "paste" means asking
+// the current owner to convert into a property on one of our windows. This
+// module hides that dance behind write()/read() promises, using a hidden
+// 1x1 never-mapped helper window as the selection endpoint.
+//
+// Supported targets when ntk owns a selection: TARGETS, UTF8_STRING and
+// STRING (latin-1, best effort). Everything else — MULTIPLE, TIMESTAMP,
+// images — is refused with SelectionNotify property None per ICCCM.
+//
+// Reads prefer UTF8_STRING and retry once with STRING when the owner
+// refuses (old Xt/Motif apps). Incremental (INCR) transfers are supported
+// on the read side, so pasting more than the server's transfer limit works.
+//
+// LIMITATION: INCR is NOT implemented on the write side — write() hands the
+// whole payload to the server in a single ChangeProperty when a requestor
+// converts. Texts approaching the server's maximum request length (~256KB
+// on servers without BIG-REQUESTS, node-x11 does not negotiate it) may fail
+// to paste into other applications.
+
+const DEFAULT_TIMEOUT = 2000;
+
+// SendEvent takes the raw 32-byte wire form of the event to deliver and
+// node-x11 has no packer for outgoing events, so build SelectionNotify
+// (code 31) by hand: CARD8 code, pad, CARD16 sequence (filled server-side),
+// TIMESTAMP, requestor WINDOW, then selection/target/property ATOMs.
+function encodeSelectionNotify(time, requestor, selection, target, property) {
+  const b = Buffer.alloc(32);
+  b[0] = 31;
+  b.writeUInt32LE(time >>> 0, 4);
+  b.writeUInt32LE(requestor >>> 0, 8);
+  b.writeUInt32LE(selection >>> 0, 12);
+  b.writeUInt32LE(target >>> 0, 16);
+  b.writeUInt32LE(property >>> 0, 20);
+  return b;
+}
+
+export default class Clipboard {
+  constructor(app) {
+    this.app = app;
+    this.X = app.X;
+    this._window = null; // hidden helper window, created on first use
+    this._owned = new Map(); // selection atom -> text we serve
+    this._atoms = null; // { TARGETS, UTF8_STRING, INCR }
+    this._transferProp = null; // property reads are converted into
+    this._ready = null;
+    this._readQueue = Promise.resolve();
+    this._onXEvent = this._onXEvent.bind(this);
+  }
+
+  /**
+   * Take ownership of a selection and serve `text` to anyone who pastes.
+   * Resolves once the server confirms the ownership; ownership (and the
+   * text) is held until another client copies or the app closes.
+   *
+   * @param {string} text
+   * @param {object} [options] { selection: 'CLIPBOARD' (default) or
+   *   'PRIMARY' (middle-click paste) — any selection atom name works }
+   * @returns {Promise<void>}
+   */
+  async write(text, { selection = 'CLIPBOARD' } = {}) {
+    await this._ensure();
+    const sel = await this._atom(selection);
+    this._owned.set(sel, String(text));
+    // time 0 = CurrentTime: best effort — ntk has no "last user input"
+    // timestamp to arbitrate ownership races with (ICCCM prefers one)
+    this.X.SetSelectionOwner(this._window.id, sel, 0);
+    // SetSelectionOwner is void: confirm via GetSelectionOwner that the
+    // server actually made us the owner
+    const owner = await new Promise((resolve, reject) =>
+      this.X.GetSelectionOwner(sel, (err, wid) => (err ? reject(err) : resolve(wid)))
+    );
+    if (owner !== this._window.id) {
+      this._owned.delete(sel);
+      throw new Error(`clipboard: failed to acquire ${selection} selection ownership`);
+    }
+  }
+
+  /**
+   * Read the current text of a selection from whoever owns it.
+   * Rejects when the selection has no owner, when the owner supports
+   * neither UTF8_STRING nor STRING, or when the owner stops responding
+   * (`timeout` ms, default 2000).
+   *
+   * @param {object} [options] { selection: 'CLIPBOARD' | 'PRIMARY' | ...,
+   *   timeout: ms to wait for the owner at each protocol step }
+   * @returns {Promise<string>}
+   */
+  read({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT } = {}) {
+    // serialize: concurrent reads would share the one transfer property on
+    // the helper window, so let each conversion finish before the next
+    const run = () => this._read(selection, timeout);
+    const result = this._readQueue.then(run, run);
+    this._readQueue = result.catch(() => {});
+    return result;
+  }
+
+  async _read(selection, timeout) {
+    await this._ensure();
+    const X = this.X;
+    const sel = await this._atom(selection);
+    const prop = this._transferProp;
+
+    let notify = await this._convert(sel, this._atoms.UTF8_STRING, prop, selection, timeout);
+    if (notify.property === 0) {
+      // property None: no owner, or the owner refused UTF8_STRING (old
+      // Xt/Motif apps) — ask again for latin-1 STRING before giving up
+      notify = await this._convert(sel, X.atoms.STRING, prop, selection, timeout);
+    }
+    if (notify.property === 0) {
+      const owner = await new Promise((resolve, reject) =>
+        X.GetSelectionOwner(sel, (err, wid) => (err ? reject(err) : resolve(wid)))
+      );
+      throw new Error(
+        owner
+          ? `clipboard: ${selection} selection owner refused both UTF8_STRING and STRING targets`
+          : `clipboard: nothing to paste — ${selection} selection has no owner`
+      );
+    }
+    const { type, data } = await this._fetchProperty(prop, selection, timeout);
+    return data.toString(type === X.atoms.STRING ? 'latin1' : 'utf8');
+  }
+
+  // lazily create the helper window, resolve atoms, hook selection events
+  _ensure() {
+    if (this._ready) return this._ready;
+    this._ready = (async () => {
+      // 1x1 and never mapped: selection ownership and transfer properties
+      // need a window id, not visible pixels. PropertyChange is in the
+      // creation mask so INCR chunk notifications arrive without a later
+      // ChangeWindowAttributes round-trip.
+      this._window = this.app.createWindow({
+        width: 1,
+        height: 1,
+        eventMask: x11.eventMask.PropertyChange
+      });
+      const [TARGETS, UTF8_STRING, INCR, transferProp] = await Promise.all([
+        this._atom('TARGETS'),
+        this._atom('UTF8_STRING'),
+        this._atom('INCR'),
+        this._atom('NTK_SELECTION')
+      ]);
+      this._atoms = { TARGETS, UTF8_STRING, INCR };
+      this._transferProp = transferProp;
+      // SelectionRequest/SelectionClear carry the owner in ev.owner, not
+      // ev.wid, so node-x11's event_consumers routing (keyed on ev.wid)
+      // never delivers them to the Window wrapper — listen on the raw
+      // client instead
+      this.X.on('event', this._onXEvent);
+    })();
+    return this._ready;
+  }
+
+  _atom(name) {
+    // predefined atoms (PRIMARY = 1, STRING = 31, ...) resolve without a
+    // round-trip; node-x11 caches interned ones after the first reply
+    return new Promise((resolve, reject) =>
+      this.X.InternAtom(false, name, (err, atom) => (err ? reject(err) : resolve(atom)))
+    );
+  }
+
+  _onXEvent(ev) {
+    if (!this._window || (ev.type !== 29 && ev.type !== 30)) return;
+    if (ev.owner !== this._window.id) return;
+    if (ev.type === 29) {
+      // SelectionClear: another client copied — we no longer answer for it
+      this._owned.delete(ev.selection);
+    } else {
+      this._onSelectionRequest(ev);
+    }
+  }
+
+  // we own the selection and somebody is pasting: write the converted data
+  // to the requestor's property and confirm (or refuse) via SelectionNotify
+  _onSelectionRequest(ev) {
+    const X = this.X;
+    const a = this._atoms;
+    const text = this._owned.get(ev.selection);
+    // obsolete requestors may pass property None — ICCCM says use the
+    // target atom as the property name then
+    let property = ev.property || ev.target;
+    // the whole answer runs from the packet parser's emit: if the
+    // connection is closing, drop it instead of throwing (see cleanup.js)
+    safeRelease(X, () => {
+      if (text === undefined) {
+        property = 0; // raced with a SelectionClear we haven't seen yet
+      } else if (ev.target === a.TARGETS) {
+        const data = Buffer.alloc(12);
+        data.writeUInt32LE(a.TARGETS, 0);
+        data.writeUInt32LE(a.UTF8_STRING, 4);
+        data.writeUInt32LE(X.atoms.STRING, 8);
+        X.ChangeProperty(0, ev.requestor, property, X.atoms.ATOM, 32, data);
+      } else if (ev.target === a.UTF8_STRING) {
+        X.ChangeProperty(0, ev.requestor, property, a.UTF8_STRING, 8, Buffer.from(text, 'utf8'));
+      } else if (ev.target === X.atoms.STRING) {
+        // latin-1 best effort: codepoints above U+00FF are lossy here;
+        // modern requestors ask for UTF8_STRING
+        X.ChangeProperty(0, ev.requestor, property, X.atoms.STRING, 8, Buffer.from(text, 'latin1'));
+      } else {
+        // unsupported target (MULTIPLE, TIMESTAMP, images, ...): refuse
+        // with property None per ICCCM
+        property = 0;
+      }
+      X.SendEvent(
+        ev.requestor,
+        0,
+        0,
+        encodeSelectionNotify(ev.time, ev.requestor, ev.selection, ev.target, property)
+      );
+    });
+  }
+
+  // ConvertSelection and wait for the owner's SelectionNotify answer
+  _convert(sel, target, prop, selectionName, timeout) {
+    return new Promise((resolve, reject) => {
+      const X = this.X;
+      const wid = this._window.id;
+      const onEvent = (ev) => {
+        if (ev.type !== 31 || ev.requestor !== wid || ev.selection !== sel) return;
+        cleanup();
+        resolve(ev);
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(
+          new Error(
+            `clipboard: timed out after ${timeout}ms waiting for the ${selectionName} selection owner to convert`
+          )
+        );
+      }, timeout);
+      const cleanup = () => {
+        clearTimeout(timer);
+        X.removeListener('event', onEvent);
+      };
+      X.on('event', onEvent);
+      X.ConvertSelection(wid, sel, target, prop, 0);
+    });
+  }
+
+  _getProperty(prop) {
+    // delete=true: for plain transfers frees the property; for INCR chunks
+    // it doubles as the "send the next chunk" handshake
+    return new Promise((resolve, reject) =>
+      this.X.GetProperty(1, this._window.id, prop, 0, 0, 0x1fffffff, (err, res) =>
+        err ? reject(err) : resolve(res)
+      )
+    );
+  }
+
+  // read the converted property, following the INCR protocol when the
+  // owner chose an incremental transfer
+  async _fetchProperty(prop, selectionName, timeout) {
+    // collect NewValue notifications from here on: with INCR the owner's
+    // next chunk lands as soon as we delete the previous property, possibly
+    // before an await below resumes — a listener installed later would
+    // miss it. The helper window gets 'property' events through the normal
+    // pipeline (PropertyNotify carries ev.wid).
+    const queue = [];
+    let waiter = null;
+    const onProperty = (ev) => {
+      if (ev.atom !== prop || ev.state !== 0) return; // 0 = NewValue
+      if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w(ev);
+      } else {
+        queue.push(ev);
+      }
+    };
+    this._window.on('property', onProperty);
+
+    const nextChunkNotify = () =>
+      new Promise((resolve, reject) => {
+        if (queue.length) return resolve(queue.shift());
+        const timer = setTimeout(() => {
+          waiter = null;
+          reject(
+            new Error(
+              `clipboard: INCR transfer of ${selectionName} selection stalled (no chunk within ${timeout}ms)`
+            )
+          );
+        }, timeout);
+        waiter = (ev) => {
+          clearTimeout(timer);
+          resolve(ev);
+        };
+      });
+
+    try {
+      const first = await this._getProperty(prop);
+      if (first.type !== this._atoms.INCR) return first;
+      // INCR (ICCCM 2.7.2): the property held a lower-bound byte count and
+      // our delete-on-read told the owner to start. Each chunk arrives as
+      // a NewValue PropertyNotify; reading it with delete=true requests
+      // the next one; a zero-length chunk ends the transfer.
+      const chunks = [];
+      let type = 0;
+      for (;;) {
+        await nextChunkNotify();
+        const part = await this._getProperty(prop);
+        if (part.data.length === 0) break;
+        type = part.type;
+        chunks.push(part.data);
+      }
+      return { type, data: Buffer.concat(chunks) };
+    } finally {
+      this._window.removeListener('property', onProperty);
+    }
+  }
+}

package/lib/cursor.js

@@ -0,0 +1,101 @@
+import { safeRelease } from './cleanup.js';
+
+// Friendly (CSS-cursor-ish) name -> glyph index in the standard X11 'cursor'
+// font (X11/cursorfont.h). Each cursor occupies two glyphs: the shape at the
+// even index and its mask at index + 1, which is why every value here is even.
+export const cursorShapes = {
+  default: 68, // XC_left_ptr
+  arrow: 68, // XC_left_ptr
+  text: 152, // XC_xterm
+  pointer: 60, // XC_hand2
+  hand: 60, // XC_hand2
+  wait: 150, // XC_watch
+  move: 52, // XC_fleur
+  crosshair: 34, // XC_crosshair
+  'ew-resize': 108, // XC_sb_h_double_arrow
+  'ns-resize': 116, // XC_sb_v_double_arrow
+  'nwse-resize': 14, // XC_bottom_right_corner
+  'nesw-resize': 12, // XC_bottom_left_corner
+  'col-resize': 108, // XC_sb_h_double_arrow
+  'row-resize': 116, // XC_sb_v_double_arrow
+  grab: 58, // XC_hand1
+  help: 92, // XC_question_arrow
+  'not-allowed': 0 // XC_X_cursor
+};
+
+/**
+ * Resolve a friendly cursor name (see `cursorShapes`) or a raw cursor-font
+ * glyph index to the glyph index. Throws on unknown names so typos surface
+ * immediately instead of silently keeping the old cursor.
+ */
+export function resolveCursorShape(nameOrShape) {
+  if (typeof nameOrShape === 'number') {
+    if (!Number.isInteger(nameOrShape) || nameOrShape < 0) {
+      throw new Error(`invalid cursor shape id: ${nameOrShape}`);
+    }
+    return nameOrShape;
+  }
+  const shape = cursorShapes[nameOrShape];
+  if (shape === undefined) {
+    throw new Error(
+      `unknown cursor name '${nameOrShape}' — valid names: ${Object.keys(cursorShapes).join(', ')}`
+    );
+  }
+  return shape;
+}
+
+/**
+ * Per-App cache of cursors created from the standard X11 'cursor' font.
+ * Cursors are server-side resources, so one is created per shape and reused
+ * for every window of the connection; `app.close()` disposes the cache.
+ * Accessed via `app.cursors` (lazily created) — user code normally never
+ * touches this directly, `wnd.setCursor(name)` goes through it.
+ */
+export class CursorCache {
+  constructor(app) {
+    this.X = app.X;
+    this._font = 0; // the 'cursor' font, opened on first use
+    this._byShape = new Map(); // glyph index -> cursor xid
+  }
+
+  /** cursor xid for a friendly name or raw glyph index, creating it on first use */
+  get(nameOrShape) {
+    const shape = resolveCursorShape(nameOrShape);
+    const cached = this._byShape.get(shape);
+    if (cached) return cached;
+
+    const X = this.X;
+    if (!this._font) {
+      this._font = X.AllocID();
+      X.OpenFont(this._font, 'cursor');
+    }
+    const cid = X.AllocID();
+    // per X convention the mask glyph follows the shape glyph in the cursor
+    // font; black foreground on white background (RGB is 16 bit per channel)
+    const black = { R: 0, G: 0, B: 0 };
+    const white = { R: 0xffff, G: 0xffff, B: 0xffff };
+    X.CreateGlyphCursor(cid, this._font, this._font, shape, shape + 1, black, white);
+    this._byShape.set(shape, cid);
+    return cid;
+  }
+
+  /** free the server-side cursors (and the font); safe to call repeatedly */
+  dispose() {
+    const X = this.X;
+    for (const cid of this._byShape.values()) {
+      safeRelease(X, () => {
+        X.FreeCursor(cid);
+        X.ReleaseID(cid);
+      });
+    }
+    this._byShape.clear();
+    if (this._font) {
+      const fid = this._font;
+      this._font = 0;
+      safeRelease(X, () => {
+        X.CloseFont(fid);
+        X.ReleaseID(fid);
+      });
+    }
+  }
+}

package/lib/index.js

@@ -1,6 +1,8 @@
 import x11 from 'x11';
 
 import App from './app.js';
+import Clipboard from './clipboard.js';
+import { CursorCache, cursorShapes, resolveCursorShape } from './cursor.js';
 import Window from './window.js';
 import Pixmap from './pixmap.js';
 import Picture from './picture.js';
@@ -98,7 +100,11 @@ export function createClient(options, callback) {
 
 export {
   App,
+  Clipboard,
   Window,
+  CursorCache,
+  cursorShapes,
+  resolveCursorShape,
   Pixmap,
   Picture,
   Image,

package/lib/renderingcontext_2d.js

@@ -41,10 +41,86 @@ const GCO_TO_PICTOP = {
   lighter: 'Add'
 };
 
-// extrude-polyline has no round caps/joins; degrade to the closest shape
-const LINE_CAP = { butt: 'butt', square: 'square', round: 'square' };
+// extrude-polyline has no round caps/joins: 'round' extrudes as butt/bevel
+// and the missing coverage is unioned in afterwards as triangle-fan disks
+// (see _strokePolys)
+const LINE_CAP = { butt: 'butt', square: 'square', round: 'butt' };
 const LINE_JOIN = { miter: 'miter', bevel: 'bevel', round: 'bevel' };
 
+/**
+ * Split a device-space polyline into dash "on" runs by arc length.
+ *
+ * `pts` is [[x, y], ...] with no consecutive duplicates; for closed subpaths
+ * the closing point is already appended, and the pattern continues around the
+ * loop as one uninterrupted walk. Returns null when the pattern cannot
+ * produce gaps (all-zero), otherwise { runs, closedLoop }: `runs` is a list
+ * of [[x, y], ...] open polylines (caps apply to each), `closedLoop` marks a
+ * closed subpath the pattern never split — stroke it closed, with no caps.
+ */
+function dashPolyline(pts, closed, pattern, offset) {
+  let total = 0;
+  for (const d of pattern) total += d;
+  if (!(total > 0)) return null;
+
+  // starting phase: offset into the pattern, wrapped into [0, total)
+  let phase = offset % total;
+  if (phase < 0) phase += total;
+  let idx = 0;
+  while (phase > 0 && phase >= pattern[idx]) {
+    phase -= pattern[idx];
+    idx = (idx + 1) % pattern.length;
+  }
+
+  let on = idx % 2 === 0; // even entries are "on", odd are gaps
+  const startedOn = on;
+  let toggled = false;
+  let remain = pattern[idx] - phase;
+  const runs = [];
+  let cur = on ? [pts[0]] : null;
+  let x0 = pts[0][0];
+  let y0 = pts[0][1];
+
+  for (let i = 1; i < pts.length; i++) {
+    const x1 = pts[i][0];
+    const y1 = pts[i][1];
+    let len = Math.hypot(x1 - x0, y1 - y0);
+    while (len > remain) {
+      // cross a dash boundary inside this segment
+      const t = len > 0 ? remain / len : 0;
+      const bx = x0 + (x1 - x0) * t;
+      const by = y0 + (y1 - y0) * t;
+      if (on) {
+        cur.push([bx, by]);
+        runs.push(cur);
+        cur = null;
+      } else {
+        cur = [[bx, by]];
+      }
+      on = !on;
+      toggled = true;
+      x0 = bx;
+      y0 = by;
+      len = Math.hypot(x1 - x0, y1 - y0);
+      idx = (idx + 1) % pattern.length;
+      remain = pattern[idx];
+    }
+    remain -= len;
+    if (on) cur.push([x1, y1]);
+    x0 = x1;
+    y0 = y1;
+  }
+  if (cur) runs.push(cur);
+
+  if (closed && !toggled) return { runs, closedLoop: startedOn };
+  // closed subpath with dashes on both sides of the seam: merge the last
+  // run into the first so no caps appear at the seam
+  if (closed && startedOn && on && runs.length > 1) {
+    const last = runs.pop();
+    runs[0] = last.concat(runs[0].slice(1));
+  }
+  return { runs, closedLoop: false };
+}
+
 function parseColor(value) {
   if (Array.isArray(value)) return value;
   const c = parseColorRaw(value);
@@ -106,6 +182,8 @@ class RenderingContext2d {
     this.lineCap = 'butt';
     this.lineJoin = 'miter';
     this.miterLimit = 10;
+    this._lineDash = [];
+    this._lineDashOffset = 0;
 
     this.fillStyle = 'white';
     this.strokeStyle = 'black';
@@ -226,6 +304,31 @@ class RenderingContext2d {
     return this._strokeStyle;
   }
 
+  /**
+   * Canvas-spec dash list: values are distances (user-space units) of
+   * alternating dashes and gaps. An empty list means solid; an odd-length
+   * list is doubled; any negative or non-finite value invalidates the whole
+   * call (it is ignored).
+   */
+  setLineDash(segments) {
+    const list = Array.from(segments ?? [], Number);
+    for (const v of list) if (!Number.isFinite(v) || v < 0) return;
+    this._lineDash = list.length % 2 ? list.concat(list) : list;
+  }
+
+  getLineDash() {
+    return this._lineDash.slice();
+  }
+
+  set lineDashOffset(value) {
+    const v = Number(value);
+    if (Number.isFinite(v)) this._lineDashOffset = v;
+  }
+
+  get lineDashOffset() {
+    return this._lineDashOffset;
+  }
+
   // ------------------------------------------------------------------
   // state
 
@@ -237,6 +340,8 @@ class RenderingContext2d {
       lineCap: this.lineCap,
       lineJoin: this.lineJoin,
       miterLimit: this.miterLimit,
+      lineDash: this._lineDash, // never mutated in place: safe to share
+      lineDashOffset: this._lineDashOffset,
       globalAlpha: this.globalAlpha,
       gco: this._gco,
       textStyle: this._textStyle,
@@ -257,6 +362,8 @@ class RenderingContext2d {
     this.lineCap = s.lineCap;
     this.lineJoin = s.lineJoin;
     this.miterLimit = s.miterLimit;
+    this._lineDash = s.lineDash;
+    this._lineDashOffset = s.lineDashOffset;
     this.globalAlpha = s.globalAlpha;
     this._gco = s.gco;
     this._textStyle = s.textStyle;
@@ -480,15 +587,88 @@ class RenderingContext2d {
     if (this.globalAlpha <= 0) return;
     // approximate transform-aware line width by the average scale factor
     const det = this._m[0] * this._m[3] - this._m[1] * this._m[2];
-    const thickness = this.lineWidth * (Math.sqrt(Math.abs(det)) || 1);
+    const scale = Math.sqrt(Math.abs(det)) || 1;
+    const thickness = this.lineWidth * scale;
+    const roundCap = this.lineCap === 'round';
+    const roundJoin = this.lineJoin === 'round';
     const stroke = extrudePolyline({
       thickness,
       cap: LINE_CAP[this.lineCap] || 'butt',
       join: LINE_JOIN[this.lineJoin] || 'miter',
       miterLimit: this.miterLimit
     });
+    // dash distances are user-space lengths; scale them like the line width
+    const dash = this._lineDash.length ? this._lineDash.map((d) => d * scale) : null;
+    const dashOffset = this._lineDashOffset * scale;
 
     const tris = [];
+    // round caps/joins: extrude-polyline extrudes them as butt/bevel (see
+    // LINE_CAP/LINE_JOIN) and we union triangle-fan disks of radius
+    // lineWidth/2 on top — a full disk at an endpoint is exactly a round
+    // cap, and a disk at an interior vertex fills the bevel notch
+    let hasRound = false;
+    const r = thickness / 2;
+    const diskSegs = Math.max(8, Math.min(32, Math.ceil(r * 2)));
+    const addDisk = (x, y) => {
+      hasRound = true;
+      let ex = x + r;
+      let ey = y;
+      for (let i = 1; i <= diskSegs; i++) {
+        const a = (i / diskSegs) * 2 * Math.PI;
+        const nx = x + r * Math.cos(a);
+        const ny = y + r * Math.sin(a);
+        tris.push(x, y, ex, ey, nx, ny);
+        ex = nx;
+        ey = ny;
+      }
+    };
+    // join disk at b (between a->b and b->c), but only where the bevel
+    // notch is visible — flattened curves have many near-collinear vertices
+    const maybeJoinDisk = (a, b, c) => {
+      const l1 = Math.hypot(b[0] - a[0], b[1] - a[1]);
+      const l2 = Math.hypot(c[0] - b[0], c[1] - b[1]);
+      if (!l1 || !l2) return;
+      let dot = ((b[0] - a[0]) * (c[0] - b[0]) + (b[1] - a[1]) * (c[1] - b[1])) / (l1 * l2);
+      dot = Math.max(-1, Math.min(1, dot));
+      // bevel-to-arc gap depth for turn angle θ: r * (1 - cos(θ/2))
+      if (r * (1 - Math.sqrt((1 + dot) / 2)) > 0.05) addDisk(b[0], b[1]);
+    };
+    // one polyline through extrusion + round-geometry post-processing;
+    // closed loops carry the seam point at both ends and get no caps
+    const extrudeRun = (pts, closed) => {
+      if (pts.length === 1) {
+        // degenerate (zero-length dash): with round caps this is a dot
+        if (roundCap) addDisk(pts[0][0], pts[0][1]);
+        return;
+      }
+      if (pts.length < 2) return;
+      const mesh = stroke.build(pts);
+      for (const tri of mesh.cells) {
+        for (let i = 0; i < 3; ++i) {
+          tris.push(mesh.positions[tri[i]][0], mesh.positions[tri[i]][1]);
+        }
+      }
+      if (roundJoin) {
+        for (let i = 1; i < pts.length - 1; i++) maybeJoinDisk(pts[i - 1], pts[i], pts[i + 1]);
+        // the seam of a closed loop is a join too (pts[0] === pts[last])
+        if (closed && pts.length > 2) maybeJoinDisk(pts[pts.length - 2], pts[0], pts[1]);
+      }
+      if (roundCap && !closed) {
+        addDisk(pts[0][0], pts[0][1]);
+        addDisk(pts[pts.length - 1][0], pts[pts.length - 1][1]);
+      }
+    };
+    // dash boundaries can duplicate run endpoints; collapse them
+    const cleanRun = (run) => {
+      const out = [run[0]];
+      for (let i = 1; i < run.length; i++) {
+        const p = run[i];
+        const q = out[out.length - 1];
+        if (Math.abs(p[0] - q[0]) > 1e-6 || Math.abs(p[1] - q[1]) > 1e-6) out.push(p);
+      }
+      return out;
+    };
+
     for (const poly of polys) {
       // drop consecutive (near-)duplicate points — zero-length segments make
       // extrude-polyline emit NaN joins that turn into spikes at the origin
@@ -508,17 +688,27 @@ class RenderingContext2d {
         if (Math.abs(fx - lx) > 1e-6 || Math.abs(fy - ly) > 1e-6) pts.push([fx, fy]);
       }
       if (pts.length < 2) continue;
-      const mesh = stroke.build(pts);
-      for (const tri of mesh.cells) {
-        for (let i = 0; i < 3; ++i) {
-          tris.push(mesh.positions[tri[i]][0], mesh.positions[tri[i]][1]);
-        }
+
+      if (!dash) {
+        extrudeRun(pts, poly.closed);
+        continue;
+      }
+      const dashed = dashPolyline(pts, poly.closed, dash, dashOffset);
+      if (!dashed) {
+        extrudeRun(pts, poly.closed);
+      } else if (dashed.closedLoop) {
+        extrudeRun(pts, true);
+      } else {
+        for (const run of dashed.runs) extrudeRun(cleanRun(run), false);
       }
     }
     if (!tris.length) return;
 
     const op = this._op();
-    const direct = this.globalAlpha >= 1 && !this.clipMask && op === this.Render.PictOp.Over;
+    // round-cap/join disks overlap the stroke body; overlapping coverage
+    // must accumulate in the clamped a8 mask (single composite) or a
+    // semi-transparent stroke style would double-blend at the overlaps
+    const direct = !hasRound && this.globalAlpha >= 1 && !this.clipMask && op === this.Render.PictOp.Over;
     const chunk = 4000 * 6;
     if (direct) {
       for (let i = 0; i < tris.length; i += chunk) {

package/lib/text/layout.js

@@ -30,8 +30,13 @@ function isWsGlyph(g) {
  * - `direction` — 'ltr' | 'rtl' | 'auto' base paragraph direction
  *
  * The result is inspectable before/without drawing: `width`, `height`, and
- * `lines[] = { x, y, baseline, width, ascent, descent, runs }` with
- * `runs[] = { x, width, run, span }` in visual order.
+ * `lines[] = { x, y, baseline, width, ascent, descent, runs, start, end }`
+ * with `runs[] = { x, width, run, span, start, end }` in visual order
+ * (`start`/`end` are logical UTF-16 ranges into the full text).
+ *
+ * `caretPosition(index)` / `indexAt(x, y)` map logical code-point indices
+ * to visual caret geometry and back (bidi/ligature/trailing-whitespace
+ * aware) — see docs/text.md.
  */
 export class TextLayout {
   constructor(fonts, content, style = {}, options = {}) {
@@ -59,6 +64,8 @@ export class TextLayout {
     });
 
     const text = spans.map((s) => s.text).join('');
+    this._text = text;
+    this._cpOffsets = null; // lazy code-point index -> code-unit offset table
     const emb = embeddingLevels(text, options.direction);
     const levels = emb.levels;
     this.baseLevel = emb.paragraphs.length ? emb.paragraphs[0].level & 1 : 0;
@@ -139,16 +146,31 @@ export class TextLayout {
     let layoutWidth = 0;
 
     for (const toks of lineTokens) {
-      // entries carry .level so reorderRuns can order them (UAX#9 L2)
+      // entries carry .level so reorderRuns can order them (UAX#9 L2);
+      // .start/.end are absolute code-unit ranges into the full text, kept
+      // for caret positioning (caretPosition / indexAt)
       let entries = [];
       for (const token of toks) {
         for (const frag of token.fragments) {
           for (const run of frag.shaped.runs) {
-            entries.push({ run, span: frag.span, level: run.level });
+            entries.push({
+              run,
+              span: frag.span,
+              level: run.level,
+              start: frag.start + run.start,
+              end: frag.start + run.end
+            });
           }
         }
       }
-      stripTrailingWhitespace(entries);
+      const lineStart = toks[0].start;
+      const lineEnd = toks[toks.length - 1].end;
+      const trailing = stripTrailingWhitespace(entries);
+      const contentEnd = trailing
+        ? trailing.start
+        : entries.length
+          ? entries[entries.length - 1].end
+          : lineStart;
       entries = reorderRuns(entries);
 
       let ascent = 0;
@@ -157,7 +179,7 @@ export class TextLayout {
       const runs = [];
       let x = 0;
       for (const e of entries) {
-        runs.push({ x, width: e.run.width, run: e.run, span: e.span });
+        runs.push({ x, width: e.run.width, run: e.run, span: e.span, start: e.start, end: e.end });
         x += e.run.width;
         const m = e.run.font.metrics(e.run.size);
         if (m.ascent > ascent) ascent = m.ascent;
@@ -172,7 +194,19 @@ export class TextLayout {
         natural = m.lineHeight;
       }
       if (x > layoutWidth) layoutWidth = x;
-      this.lines.push({ x: 0, y, baseline: y + ascent, width: x, ascent, descent, runs });
+      this.lines.push({
+        x: 0,
+        y,
+        baseline: y + ascent,
+        width: x,
+        ascent,
+        descent,
+        runs,
+        start: lineStart,
+        end: lineEnd,
+        _contentEnd: contentEnd,
+        _trailing: trailing
+      });
       y += natural * lineHeightMul;
     }
 
@@ -204,7 +238,7 @@ export class TextLayout {
       if (fragText.length > 0) {
         const fragLevels = normalizedLevels(levels, pos, pos + fragText.length);
         const shaped = this.fonts._shapeCached(fragText, span, fragLevels);
-        fragments.push({ text: fragText, span, shaped });
+        fragments.push({ text: fragText, span, shaped, start: pos });
         width += shaped.width;
       }
       pos = fragEnd;
@@ -219,7 +253,7 @@ export class TextLayout {
         wsWidth = m[0].length * spaceGlyph.advanceWidth * last.span.font.scale(last.span.size);
       }
     }
-    return { fragments, width, wsWidth, required };
+    return { fragments, width, wsWidth, required, start, end };
   }
 
   // split an over-wide token at the widest cluster boundary that fits
@@ -249,7 +283,9 @@ export class TextLayout {
           hi = mid - 1;
         }
       }
-      if (best) headFrags.push({ text: best.text, span: frag.span, shaped: best.shaped });
+      if (best) {
+        headFrags.push({ text: best.text, span: frag.span, shaped: best.shaped, start: frag.start });
+      }
 
       const restFrags = [];
       const restText = frag.text.slice(best ? best.len : 0);
@@ -257,26 +293,30 @@ export class TextLayout {
         restFrags.push({
           text: restText,
           span: frag.span,
-          shaped: this.fonts._shapeCached(restText, frag.span, '0')
+          shaped: this.fonts._shapeCached(restText, frag.span, '0'),
+          start: frag.start + (best ? best.len : 0)
         });
       }
       restFrags.push(...token.fragments.slice(i + 1));
       const sum = (frags) => frags.reduce((w, f) => w + f.shaped.width, 0);
+      const splitAt = restFrags.length ? restFrags[0].start : token.end;
       const head = headFrags.length
-        ? { fragments: headFrags, width: sum(headFrags), wsWidth: 0, required: false }
+        ? { fragments: headFrags, width: sum(headFrags), wsWidth: 0, required: false, start: token.start, end: splitAt }
         : null;
       const rest = {
         fragments: restFrags,
         width: sum(restFrags),
         wsWidth: token.wsWidth,
-        required: token.required
+        required: token.required,
+        start: splitAt,
+        end: token.end
       };
       return [head, rest];
     }
     // everything fit after all (float rounding): no split needed
     return [
       { ...token, required: false },
-      { fragments: [], width: 0, wsWidth: 0, required: token.required }
+      { fragments: [], width: 0, wsWidth: 0, required: token.required, start: token.end, end: token.end }
     ];
   }
 
@@ -308,11 +348,283 @@ export class TextLayout {
     ctx._markDirty();
     return this;
   }
+
+  // ---- caret positioning / hit testing ----------------------------------
+  //
+  // Both methods speak logical **code-point** indices (what you get from
+  // `Array.from(text)` / caret arithmetic on code points), converted
+  // internally to the code-unit ranges the shaped runs carry.
+  //
+  // Conventions (v1):
+  // - Direction boundaries: a single caret, placed at the trailing edge of
+  //   the character logically before the index (the run containing the
+  //   previous character wins). At a line start the leading edge of the
+  //   run containing the index is used. Indices on both sides of a
+  //   direction boundary may therefore map to the same visual x.
+  // - Ligature/cluster interior indices interpolate proportionally (by
+  //   code-point count) across the cluster's advance.
+  // - An index just after a hard break belongs to the next line; the index
+  //   of the break character itself sits at the end of its line. An index
+  //   at a soft wrap boundary belongs to the start of the wrapped line.
+  // - Trailing whitespace stripped from a line end still advances the
+  //   caret, extending past the line edge on the paragraph-direction side.
+
+  /** lazy code-point index -> code-unit offset table (n + 1 entries) */
+  _offsets() {
+    if (!this._cpOffsets) {
+      const offs = [];
+      let cu = 0;
+      for (const ch of this._text) {
+        offs.push(cu);
+        cu += ch.length;
+      }
+      offs.push(cu);
+      this._cpOffsets = offs;
+    }
+    return this._cpOffsets;
+  }
+
+  /** code-unit offset -> code-point index (binary search) */
+  _cpOf(cu) {
+    const offs = this._offsets();
+    let lo = 0;
+    let hi = offs.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (offs[mid] <= cu) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo;
+  }
+
+  /**
+   * Visual caret geometry for a logical code-point index in
+   * `[0, codePointCount]` (out-of-range indices clamp).
+   *
+   * @returns {{ x, y, height, line }} `x` is the caret's visual x within
+   *   the layout box (alignment included), `y` the top of the line box,
+   *   `height` = ascent + descent, `line` the line index.
+   */
+  caretPosition(index) {
+    const offs = this._offsets();
+    const n = offs.length - 1;
+    const i = Math.max(0, Math.min(Math.floor(index), n));
+    const cu = offs[i];
+    let li = 0;
+    for (let l = this.lines.length - 1; l >= 0; l--) {
+      if (cu >= this.lines[l].start) {
+        li = l;
+        break;
+      }
+    }
+    const line = this.lines[li];
+    return {
+      x: this._caretXInLine(line, cu),
+      y: line.y,
+      height: line.ascent + line.descent,
+      line: li
+    };
+  }
+
+  /**
+   * Hit test: the logical code-point index of the caret boundary closest
+   * to layout-box coordinates (x, y). Picks the line by y (clamping above
+   * the first / below the last line), then the nearest boundary by x in
+   * visual order — a click past the midpoint of a cluster snaps to its far
+   * edge. Inverse of `caretPosition` up to bidi boundary ambiguity.
+   */
+  indexAt(x, y) {
+    const lines = this.lines;
+    if (lines.length === 0) return 0;
+    let li = lines.length - 1;
+    for (let l = 0; l < lines.length; l++) {
+      const bottom = l + 1 < lines.length ? lines[l + 1].y : Infinity;
+      if (y < bottom) {
+        li = l;
+        break;
+      }
+    }
+    const line = lines[li];
+    const lx = x - line.x;
+    const t = line._trailing;
+    const rightSide = !(this.baseLevel & 1);
+    if (t && (rightSide ? lx > line.width : lx < 0)) {
+      // in the stripped trailing-whitespace zone past the line edge
+      const dist = rightSide ? lx - line.width : -lx;
+      let pos = t.start;
+      let edge = 0;
+      for (const g of t.glyphs) {
+        if (dist < edge + g.ax / 2) return this._cpOf(pos);
+        edge += g.ax;
+        pos += g.len;
+      }
+      return this._cpOf(pos);
+    }
+    if (line.runs.length === 0) return this._cpOf(line.start);
+    const cx = Math.max(0, Math.min(lx, line.width));
+    let target = line.runs[line.runs.length - 1];
+    for (const r of line.runs) {
+      if (cx <= r.x + r.width) {
+        target = r;
+        break;
+      }
+    }
+    return this._cpOf(this._runIndexAt(target, cx));
+  }
+
+  /** caret x (layout-box coords) for an absolute code-unit offset on `line` */
+  _caretXInLine(line, cu) {
+    const t = line._trailing;
+    if (t && cu > t.start) {
+      // inside (or past) the stripped trailing whitespace: extend beyond
+      // the visual line edge on the paragraph-direction side
+      let adv = 0;
+      let pos = t.start;
+      for (const g of t.glyphs) {
+        if (cu >= pos + g.len) {
+          adv += g.ax;
+          pos += g.len;
+        } else {
+          if (cu > pos) adv += (g.ax * (cu - pos)) / g.len;
+          break;
+        }
+      }
+      return this.baseLevel & 1 ? line.x - adv : line.x + line.width + adv;
+    }
+    if (line.runs.length === 0) return line.x;
+    const cc = Math.min(cu, line._contentEnd);
+    // previous-character rule: the run containing the char before the index
+    let target = null;
+    if (cc > line.start) {
+      for (const r of line.runs) {
+        if (r.start < cc && cc <= r.end) {
+          target = r;
+          break;
+        }
+      }
+    }
+    if (!target) {
+      for (const r of line.runs) {
+        if (r.start <= cc && cc < r.end) {
+          target = r;
+          break;
+        }
+      }
+    }
+    if (!target) target = line.runs[this.baseLevel & 1 ? line.runs.length - 1 : 0];
+    return line.x + this._boundaryX(target, cc);
+  }
+
+  /** x of logical boundary `cu` within a positioned line run (run-local + run.x) */
+  _boundaryX(lineRun, cu) {
+    const { run, start, end } = lineRun;
+    let x = lineRun.x;
+    if (run.direction === 'rtl') {
+      // glyphs stored in visual order; leftmost glyph is logically last
+      let pos = end;
+      for (const g of run.glyphs) {
+        const len = cuLength(g.codePoints);
+        if (len === 0) {
+          x += g.ax;
+          continue;
+        }
+        if (cu >= pos) return x;
+        if (cu > pos - len) {
+          // fraction of the cluster left of the caret = code points after cu
+          const cps = g.codePoints;
+          let k = 0;
+          let c = pos;
+          for (let j = cps.length - 1; j >= 0; j--) {
+            const l = cps[j] > 0xffff ? 2 : 1;
+            if (c - l < cu) break;
+            c -= l;
+            k++;
+          }
+          return x + (g.ax * k) / cps.length;
+        }
+        pos -= len;
+        x += g.ax;
+      }
+      return x;
+    }
+    let pos = start;
+    for (const g of run.glyphs) {
+      const len = cuLength(g.codePoints);
+      if (len === 0) {
+        x += g.ax;
+        continue;
+      }
+      if (cu <= pos) return x;
+      if (cu < pos + len) {
+        const cps = g.codePoints;
+        let k = 0;
+        let c = pos;
+        for (const cp of cps) {
+          const l = cp > 0xffff ? 2 : 1;
+          if (c + l > cu) break;
+          c += l;
+          k++;
+        }
+        return x + (g.ax * k) / cps.length;
+      }
+      pos += len;
+      x += g.ax;
+    }
+    return x;
+  }
+
+  /** nearest caret boundary (code units) to line-local x within a line run */
+  _runIndexAt(lineRun, lx) {
+    const { run, start, end } = lineRun;
+    const rtl = run.direction === 'rtl';
+    let pos = rtl ? end : start;
+    let gx = lineRun.x;
+    for (const g of run.glyphs) {
+      const len = cuLength(g.codePoints);
+      if (len === 0 || g.ax <= 0) {
+        gx += g.ax;
+        if (g.ax <= 0) pos += rtl ? -len : len;
+        continue;
+      }
+      if (lx <= gx + g.ax) {
+        const cps = g.codePoints;
+        let k = Math.round(((lx - gx) / g.ax) * cps.length);
+        k = Math.max(0, Math.min(k, cps.length));
+        // move k code points into the cluster from its left edge
+        let c = pos;
+        if (rtl) {
+          for (let j = cps.length - 1; j >= cps.length - k; j--) {
+            c -= cps[j] > 0xffff ? 2 : 1;
+          }
+        } else {
+          for (let j = 0; j < k; j++) c += cps[j] > 0xffff ? 2 : 1;
+        }
+        return c;
+      }
+      pos += rtl ? -len : len;
+      gx += g.ax;
+    }
+    return pos;
+  }
+}
+
+// UTF-16 length of a glyph cluster's codePoints array
+function cuLength(codePoints) {
+  let len = 0;
+  for (const cp of codePoints) len += cp > 0xffff ? 2 : 1;
+  return len;
 }
 
 // Drop trailing whitespace glyphs from the logical end of a line.
 // Shaped runs are shared via the shaping cache — clone instead of mutating.
+// Returns what was stripped — `{ start, glyphs: [{ ax, len }] }` in logical
+// order (absolute code-unit start, per-glyph advance and code-unit length) —
+// so caret positioning can still walk through trailing spaces, or null when
+// nothing was stripped. Adjusts the surviving entries' logical `end`.
 function stripTrailingWhitespace(entries) {
+  const stripped = [];
+  let strippedStart = null;
+  const result = () => (stripped.length ? { start: strippedStart, glyphs: stripped } : null);
   for (let i = entries.length - 1; i >= 0; i--) {
     const run = entries[i].run;
     // rtl runs store glyphs in visual order: their logical end is index 0
@@ -325,21 +637,35 @@ function stripTrailingWhitespace(entries) {
       count++;
       wsWidth += g.ax;
     }
-    if (count === 0) return;
+    if (count === 0) return result();
+    // stripped glyphs in logical order (rtl glyph storage is reversed)
+    const tail = fromFront
+      ? run.glyphs.slice(0, count).reverse()
+      : run.glyphs.slice(run.glyphs.length - count);
+    let cuStripped = 0;
+    const info = tail.map((g) => {
+      const len = cuLength(g.codePoints);
+      cuStripped += len;
+      return { ax: g.ax, len };
+    });
+    stripped.unshift(...info);
+    strippedStart = entries[i].end - cuStripped;
     if (count === run.glyphs.length) {
       entries.splice(i, 1);
       continue;
     }
     entries[i] = {
       ...entries[i],
+      end: entries[i].end - cuStripped,
       run: {
         ...run,
         glyphs: fromFront ? run.glyphs.slice(count) : run.glyphs.slice(0, -count),
         width: run.width - wsWidth
       }
     };
-    return;
+    return result();
   }
+  return result();
 }
 
 // compact levels key for the shaping cache: single char when uniform

package/lib/window.js

@@ -577,25 +577,52 @@ export default class Window extends Drawable {
     const wid = this.id;
     // legacy WM_NAME is latin-1 only (node-x11 encodes plain strings as
     // latin1) — kept for old window managers
-    X.ChangeProperty(0, wid, X.atoms.WM_NAME, X.atoms.STRING, 8, title);
+    safeRelease(X, () => {
+      X.ChangeProperty(0, wid, X.atoms.WM_NAME, X.atoms.STRING, 8, title);
+    });
     // modern WMs prefer the EWMH _NET_WM_NAME property, which is UTF-8;
     // interned atoms are cached by node-x11, so this round-trips only once.
     // The lookups are async: by the time they resolve the window may be
     // destroyed (ChangeProperty would BadWindow) or retitled (an older
     // write would clobber a newer one) — the serial/destroyed guards drop
-    // the stale write in both cases.
+    // the stale write in both cases. Every request in the chain is issued
+    // via safeRelease: replies drain while the connection is closing
+    // (app.close() pings before terminating), and a follow-up request from
+    // inside a reply callback would otherwise throw 'client is in closing
+    // state' from the stream read handler, where no user code can catch it.
     const serial = ++this._titleSerial;
-    X.InternAtom(false, '_NET_WM_NAME', (err, netWmName) => {
-      X.InternAtom(false, 'UTF8_STRING', (err2, utf8String) => {
-        if (err || err2 || this._destroyed || serial !== this._titleSerial) return;
+    safeRelease(X, () => {
+      X.InternAtom(false, '_NET_WM_NAME', (err, netWmName) => {
+        if (err) return;
         safeRelease(X, () => {
-          X.ChangeProperty(0, wid, netWmName, utf8String, 8, Buffer.from(title, 'utf8'));
+          X.InternAtom(false, 'UTF8_STRING', (err2, utf8String) => {
+            if (err2 || this._destroyed || serial !== this._titleSerial) return;
+            safeRelease(X, () => {
+              X.ChangeProperty(0, wid, netWmName, utf8String, 8, Buffer.from(title, 'utf8'));
+            });
+          });
         });
       });
     });
     return this;
   }
 
+  /**
+   * Set the mouse cursor shown over this window. Accepts a friendly name
+   * ('text', 'pointer', 'wait', ... — see cursorShapes in lib/cursor.js and
+   * docs/window.md) or a raw X11 cursor-font glyph index. Cursors are
+   * created once per connection and cached on the app. `setCursor(null)`
+   * restores the parent window's cursor (X cursor = None). Throws
+   * synchronously on unknown names.
+   */
+  setCursor(nameOrShape) {
+    const cursor = nameOrShape == null ? 0 : this.app.cursors.get(nameOrShape);
+    safeRelease(this.X, () => {
+      this.X.ChangeWindowAttributes(this.id, { cursor }, () => {});
+    });
+    return this;
+  }
+
   setMouseHintOnly(isOn) {
     if (isOn && !(this.eventMask & x11.eventMask.PointerMotionHint)) {
       this.eventMask |= x11.eventMask.PointerMotionHint;
@@ -659,12 +686,22 @@ export default class Window extends Drawable {
   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);
+    // same deferred-chain shape as setTitle: each step runs from a reply
+    // callback and must no-op instead of throwing if the connection
+    // started closing (or the window died) while the replies were in flight
+    safeRelease(X, () => {
+      X.InternAtom(false, 'WM_PROTOCOLS', (err, WM_PROTOCOLS) => {
+        if (err) return;
+        safeRelease(X, () => {
+          X.InternAtom(false, 'WM_DELETE_WINDOW', (err2, WM_DELETE_WINDOW) => {
+            if (err2 || this._destroyed) return;
+            const data = Buffer.alloc(4);
+            data.writeUInt32LE(WM_DELETE_WINDOW, 0);
+            safeRelease(X, () => {
+              X.ChangeProperty(0, wid, WM_PROTOCOLS, X.atoms.ATOM, 32, data);
+            });
+          });
+        });
       });
     });
   }

package/package.json

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