ntk 5.2.0 → 5.3.0

package/lib/clipboard.js

@@ -2,7 +2,7 @@ import x11 from 'x11';
 
 import { safeRelease } from './cleanup.js';
 
-// Clipboard (app.clipboard): ICCCM selection transfer for plain text.
+// Clipboard (app.clipboard): ICCCM selection transfer.
 //
 // X has no clipboard buffer — "copy" means owning a selection atom
 // (CLIPBOARD for explicit copy/paste, PRIMARY for middle-click paste) and
@@ -11,54 +11,100 @@ import { safeRelease } from './cleanup.js';
 // 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.
+// As an owner, ntk answers the three targets ICCCM 2.6.2 makes mandatory
+// (TARGETS, TIMESTAMP, MULTIPLE) plus whatever the caller offered: a string
+// is served as UTF8_STRING and STRING (latin-1, best effort), an object maps
+// target names to payloads, so HTML, images and — later — XDND drags are the
+// same machinery. Payloads larger than one request are transferred
+// incrementally (INCR, ICCCM 2.7.2), in both directions.
 //
 // 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.
+// refuses (old Xt/Motif apps).
 
 const DEFAULT_TIMEOUT = 2000;
+// An INCR transfer we are feeding is driven entirely by the requestor: each
+// chunk goes out in answer to its property deletion. A requestor that stops
+// (or dies mid-paste) would otherwise leave us holding its payload and an
+// event mask on its window forever, so give up after this much silence.
+const INCR_TIMEOUT = 10000;
+// node-x11 writes ChangeProperty's length field as a CARD16 — only PutImage
+// emits the BIG-REQUESTS extended form — so a request can never exceed
+// 65535 four-byte units however much the server allows.
+const REQUEST_UNITS_LIMIT = 0xffff;
+
+const isBinary = (value) => ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+
+// payload bytes for one target: text is UTF-8 (latin-1 for STRING, which is
+// defined as latin-1), binary is taken as-is
+const encodePayload = (value, name) => {
+  if (typeof value === 'string') return Buffer.from(value, name === 'STRING' ? 'latin1' : 'utf8');
+  if (Buffer.isBuffer(value)) return value;
+  if (ArrayBuffer.isView(value))
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  if (value instanceof ArrayBuffer) return Buffer.from(value);
+  throw new TypeError(`clipboard: the ${name} payload must be a string or binary data`);
+};
 
 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._owned = new Map(); // selection atom -> { time, targets }
+    this._atoms = null; // { TARGETS, TIMESTAMP, MULTIPLE, ATOM_PAIR, UTF8_STRING, INCR }
     this._transferProp = null; // property reads are converted into
+    this._timeProp = null; // property the server-timestamp trick appends to
+    this._transfers = new Map(); // `requestor:property` -> INCR transfer we feed
+    this._watched = new Map(); // requestor wid -> { count, mask } while feeding
+    this._transferLimit = null; // bytes one ChangeProperty can carry
+    this._incrTimeout = INCR_TIMEOUT;
     this._ready = null;
     this._readQueue = Promise.resolve();
+    this._fixes = null; // XFixes extension, required on first watch()
+    this._fixesFirstEvent = -1; // its event base, to recognise its events
+    this._selectionWatchers = new Map(); // selection atom -> { name, handlers }
     this._onXEvent = this._onXEvent.bind(this);
   }
 
   /**
-   * Take ownership of a selection and serve `text` to anyone who pastes.
+   * Take ownership of a selection and serve `data` 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.
+   * data) is held until another client copies or the app closes.
+   *
+   * `data` is either a string — offered as UTF8_STRING and STRING — or an
+   * object (or Map) from target name to payload, which is how richer
+   * formats are published:
+   *
+   *   await app.clipboard.write({
+   *     'text/plain;charset=utf-8': 'hello',
+   *     'text/html': '<b>hello</b>',
+   *     'image/png': pngBuffer
+   *   });
    *
-   * @param {string} text
+   * String payloads are encoded UTF-8 (latin-1 for the STRING target);
+   * Buffers/TypedArrays are served as-is. TARGETS, TIMESTAMP and MULTIPLE
+   * are answered by ntk itself and cannot be offered as data.
+   *
+   * @param {string|object|Map} data
    * @param {object} [options] { selection: 'CLIPBOARD' (default) or
-   *   'PRIMARY' (middle-click paste) — any selection atom name works }
+   *   'PRIMARY' (middle-click paste) — any selection atom name works;
+   *   time: the server timestamp of the event that triggered the copy
+   *   (ICCCM 2.1). Without one ntk asks the server for the current time
+   *   rather than using CurrentTime, which ICCCM forbids }
    * @returns {Promise<void>}
    */
-  async write(text, { selection = 'CLIPBOARD' } = {}) {
+  async write(data, { selection = 'CLIPBOARD', time } = {}) {
     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);
+    const [sel, targets] = await Promise.all([this._atom(selection), this._encode(data)]);
+    // ICCCM 2.1: never CurrentTime. The timestamp of the event that
+    // triggered the copy is the right one — it is what arbitrates a race
+    // with another app copying at the same moment. Without one, "now" is
+    // still a real timestamp, and one no server will reject as stale.
+    const stamp = time === undefined ? await this._serverTime() : time >>> 0;
+    this._owned.set(sel, { time: stamp, targets });
+    this.X.SetSelectionOwner(this._window.id, sel, stamp);
     // SetSelectionOwner is void: confirm via GetSelectionOwner that the
-    // server actually made us the owner
+    // server actually made us the owner (it ignores a stale timestamp)
     const owner = await new Promise((resolve, reject) =>
       this.X.GetSelectionOwner(sel, (err, wid) => (err ? reject(err) : resolve(wid)))
     );
@@ -78,15 +124,86 @@ export default class Clipboard {
    *   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);
+  read({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT, target } = {}) {
+    return this._serialize(() =>
+      target === undefined
+        ? this._read(selection, timeout)
+        : this._readTarget(selection, target, timeout)
+    );
+  }
+
+  /**
+   * What the current owner of a selection can convert to, as target names.
+   *
+   *   const offered = await app.clipboard.targets();
+   *   if (offered.includes('image/png')) { ... }
+   *
+   * This is the question to ask before `read({ target })`: an owner answers
+   * `TARGETS` cheaply, where guessing costs a failed conversion per guess.
+   * Returns `[]` when nothing owns the selection.
+   *
+   * @param {object} [options] { selection, timeout }
+   * @returns {Promise<string[]>}
+   */
+  targets({ selection = 'CLIPBOARD', timeout = DEFAULT_TIMEOUT } = {}) {
+    return this._serialize(() => this._targets(selection, timeout));
+  }
+
+  /** Concurrent conversions would share the one transfer property on the
+   * helper window, so let each finish before the next starts. */
+  _serialize(run) {
     const result = this._readQueue.then(run, run);
     this._readQueue = result.catch(() => {});
     return result;
   }
 
+  async _targets(selection, timeout) {
+    await this._ensure();
+    const sel = await this._atom(selection);
+    const prop = this._transferProp;
+    const notify = await this._convert(sel, this._atoms.TARGETS, prop, selection, timeout);
+    if (notify.property === 0) return [];
+    const { data, format } = await this._fetchProperty(prop, selection, timeout);
+    // an INCR reassembly reports no format, and a target list is far too
+    // small to arrive that way — so only a stated non-32 format disqualifies
+    if (format !== undefined && format !== 32) return [];
+    const atoms = [];
+    for (let o = 0; o + 4 <= data.length; o += 4) atoms.push(data.readUInt32LE(o));
+    const names = await Promise.all(atoms.map((atom) => this._atomName(atom)));
+    return names.filter(Boolean);
+  }
+
+  /**
+   * Read one named target, as bytes. The mirror of writing one: what
+   * `write({ 'image/png': buf })` publishes, this is how another ntk app
+   * gets it back.
+   */
+  async _readTarget(selection, target, timeout) {
+    await this._ensure();
+    const sel = await this._atom(selection);
+    const atom = await this._atom(target);
+    const prop = this._transferProp;
+    const notify = await this._convert(sel, atom, prop, selection, timeout);
+    if (notify.property === 0) {
+      const owner = await new Promise((resolve, reject) =>
+        this.X.GetSelectionOwner(sel, (err, wid) => (err ? reject(err) : resolve(wid)))
+      );
+      throw new Error(
+        owner
+          ? `clipboard: ${selection} selection owner cannot convert to ${target}`
+          : `clipboard: nothing to paste — ${selection} selection has no owner`
+      );
+    }
+    const { data } = await this._fetchProperty(prop, selection, timeout);
+    return data;
+  }
+
+  _atomName(atom) {
+    return new Promise((resolve) =>
+      this.X.GetAtomName(atom, (err, name) => resolve(err ? null : name))
+    );
+  }
+
   async _read(selection, timeout) {
     await this._ensure();
     const X = this.X;
@@ -126,23 +243,143 @@ export default class Clipboard {
         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 };
+      const [TARGETS, TIMESTAMP, MULTIPLE, ATOM_PAIR, UTF8_STRING, INCR, transferProp, timeProp] =
+        await Promise.all(
+          [
+            'TARGETS',
+            'TIMESTAMP',
+            'MULTIPLE',
+            'ATOM_PAIR',
+            'UTF8_STRING',
+            'INCR',
+            'NTK_SELECTION',
+            'NTK_TIME'
+          ].map((name) => this._atom(name))
+        );
+      this._atoms = { TARGETS, TIMESTAMP, MULTIPLE, ATOM_PAIR, UTF8_STRING, INCR };
       this._transferProp = transferProp;
+      this._timeProp = timeProp;
       // 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
+      // client instead. INCR chunk pacing needs PropertyNotify for the
+      // requestor's window, which is not ours either.
       this.X.on('event', this._onXEvent);
     })();
     return this._ready;
   }
 
+  /**
+   * Call `handler` whenever a selection changes hands.
+   *
+   *   const unwatch = await app.clipboard.watch('CLIPBOARD', (ev) => {
+   *     pasteItem.disabled = ev.owner === 0;
+   *   });
+   *   unwatch();
+   *
+   * The alternative is polling `read()`, which is a full conversion round
+   * trip against whatever foreign client owns the selection — and a two
+   * second wait when that client is wedged. This is a server-side
+   * subscription instead: the server tells us, and it costs nothing until
+   * something actually changes.
+   *
+   * `ev` is `{ selection, owner, timestamp, selectionTimestamp, reason }`,
+   * where `reason` is `'new-owner'` when someone took the selection,
+   * `'destroyed'` when the owning window went away, and `'closed'` when the
+   * owning client disconnected. `owner` is 0 when the selection ends up
+   * unowned, which is the case an edit menu wants: nothing to paste.
+   *
+   * Watchers share one server-side registration per selection, so watching
+   * the same selection twice costs one extra callback and no extra protocol.
+   *
+   * @param {string} selection selection atom name, e.g. 'CLIPBOARD' or 'PRIMARY'
+   * @param {function} handler called with the event
+   * @returns {Promise<function>} call it to stop watching
+   */
+  async watch(selection, handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('clipboard: watch needs a handler function');
+    }
+    await this._ensure();
+    const fixes = await this._ensureFixes();
+    const sel = await this._atom(selection);
+
+    let entry = this._selectionWatchers.get(sel);
+    if (!entry) {
+      entry = { name: selection, handlers: new Set() };
+      this._selectionWatchers.set(sel, entry);
+      const mask =
+        fixes.SelectionEventMask.SetSelectionOwner |
+        fixes.SelectionEventMask.SelectionWindowDestroy |
+        fixes.SelectionEventMask.SelectionClientClose;
+      safeRelease(this.X, () => fixes.SelectSelectionInput(this._window.id, sel, mask));
+    }
+    entry.handlers.add(handler);
+
+    let stopped = false;
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      const current = this._selectionWatchers.get(sel);
+      if (!current) return;
+      current.handlers.delete(handler);
+      if (current.handlers.size) return;
+      // last watcher for this selection: drop the server-side registration
+      this._selectionWatchers.delete(sel);
+      safeRelease(this.X, () => fixes.SelectSelectionInput(this._window.id, sel, 0));
+    };
+  }
+
+  /** XFixes, required once. Rejects with something readable on a server
+   * without it — every X server since about 2004 has had it, so this is a
+   * "your server is unusual" error rather than a routine fallback. */
+  _ensureFixes() {
+    if (this._fixes) return this._fixes;
+    this._fixes = new Promise((resolve, reject) => {
+      this.X.require('fixes', (err, fixes) => {
+        if (err || !fixes) {
+          this._fixes = null; // let a later call try again
+          return reject(
+            new Error(
+              'clipboard: this X server has no XFixes extension, so selection ' +
+                `changes cannot be watched${err ? `: ${err.message}` : ''}`
+            )
+          );
+        }
+        this._fixesFirstEvent = fixes.firstEvent;
+        resolve(fixes);
+      });
+    });
+    return this._fixes;
+  }
+
+  /** An XFixes SelectionNotify: translate the subtype and fan out. */
+  _onSelectionChange(ev, fixes) {
+    const entry = this._selectionWatchers.get(ev.selection);
+    if (!entry) return;
+    const reason =
+      ev.subtype === fixes.SelectionEvent.SelectionWindowDestroy
+        ? 'destroyed'
+        : ev.subtype === fixes.SelectionEvent.SelectionClientClose
+          ? 'closed'
+          : 'new-owner';
+    const detail = {
+      selection: entry.name,
+      owner: ev.owner,
+      timestamp: ev.timestamp,
+      selectionTimestamp: ev.selectionTimestamp,
+      reason
+    };
+    // a throwing handler must not cost the others their event
+    for (const handler of [...entry.handlers]) {
+      try {
+        handler(detail);
+      } catch (err) {
+        console.warn(`ntk: clipboard watch handler threw: ${err.message}`);
+      }
+    }
+  }
+
   _atom(name) {
     // predefined atoms (PRIMARY = 1, STRING = 31, ...) resolve without a
     // round-trip; node-x11 caches interned ones after the first reply
@@ -151,64 +388,329 @@ export default class Clipboard {
     );
   }
 
+  // every server call from an event handler runs inside the packet parser's
+  // emit: if the connection is closing, drop it instead of throwing
+  _send(fn) {
+    safeRelease(this.X, fn);
+  }
+
+  // name -> payload map for one selection, target names resolved to atoms
+  async _encode(data) {
+    const a = this._atoms;
+    if (data === null || typeof data !== 'object') {
+      const text = String(data);
+      const STRING = this.X.atoms.STRING;
+      return new Map([
+        [a.UTF8_STRING, { type: a.UTF8_STRING, format: 8, data: Buffer.from(text, 'utf8') }],
+        [STRING, { type: STRING, format: 8, data: Buffer.from(text, 'latin1') }]
+      ]);
+    }
+    if (isBinary(data)) {
+      throw new TypeError(
+        "clipboard: binary data needs a target name — write({ 'image/png': buffer })"
+      );
+    }
+    const entries = data instanceof Map ? [...data] : Object.entries(data);
+    if (!entries.length) throw new TypeError('clipboard: write() needs at least one target');
+    const atoms = await Promise.all(entries.map(([name]) => this._atom(name)));
+    const targets = new Map();
+    entries.forEach(([name, value], i) => {
+      const atom = atoms[i];
+      if (atom === a.TARGETS || atom === a.TIMESTAMP || atom === a.MULTIPLE) {
+        throw new TypeError(`clipboard: ${name} is answered by ntk and cannot be offered as data`);
+      }
+      targets.set(atom, { type: atom, format: 8, data: encodePayload(value, name) });
+    });
+    return targets;
+  }
+
+  // A current server timestamp, the way X clients without a triggering
+  // event get one: append zero bytes to a property on a window we watch and
+  // take the time from the PropertyNotify it generates. Falls back to 0
+  // (CurrentTime) rather than making write() hang.
+  _serverTime() {
+    return new Promise((resolve) => {
+      const done = (time) => {
+        clearTimeout(timer);
+        this._window.removeListener('property', onProperty);
+        resolve(time);
+      };
+      const onProperty = (ev) => {
+        if (ev.atom === this._timeProp && ev.state === 0) done(ev.time >>> 0);
+      };
+      const timer = setTimeout(() => done(0), DEFAULT_TIMEOUT);
+      timer.unref?.();
+      this._window.on('property', onProperty);
+      const empty = Buffer.alloc(0);
+      this.X.ChangeProperty(2, this._window.id, this._timeProp, this.X.atoms.STRING, 8, empty);
+    });
+  }
+
+  // largest payload one ChangeProperty can carry; beyond it a conversion is
+  // answered incrementally. Tests lower it to exercise INCR cheaply.
+  _limit() {
+    if (this._transferLimit === null) {
+      const offered = this.app.display.max_request_length || REQUEST_UNITS_LIMIT;
+      const units = Math.min(offered, REQUEST_UNITS_LIMIT);
+      this._transferLimit = units * 4 - 24 - 4; // ChangeProperty header, padding
+    }
+    return this._transferLimit;
+  }
+
   _onXEvent(ev) {
-    if (!this._window || (ev.type !== 29 && ev.type !== 30)) return;
+    if (!this._window) return;
+    // XFixes events carry a server-assigned type above the core range, so
+    // this cannot be confused with core SelectionNotify, which is 31
+    if (ev.type === this._fixesFirstEvent && this._selectionWatchers.size) {
+      this._fixes?.then(
+        (fixes) => this._onSelectionChange(ev, fixes),
+        () => {}
+      );
+      return;
+    }
+    if (ev.type === 28) {
+      // PropertyNotify, state 1 = Deleted: a requestor consumed the INCR
+      // chunk we gave it and is asking for the next one
+      if (ev.state === 1 && this._transfers.size) this._onChunkConsumed(ev);
+      return;
+    }
+    if (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
+      // SelectionClear: another client copied — we no longer answer for it.
+      // Transfers already under way keep their own copy of the data and
+      // must still finish (ICCCM 2.7.2).
       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
+  // we own the selection and somebody is pasting
   _onSelectionRequest(ev) {
-    const X = this.X;
-    const a = this._atoms;
-    const text = this._owned.get(ev.selection);
+    this._answer(ev).catch(() => {
+      // a step of the conversion failed outright (a requestor that vanished
+      // mid-paste, most likely) after we had already answered: nothing left
+      // to say, and the requestor's own timeout covers it
+    });
+  }
+
+  // write the converted data to the requestor's property and confirm (or
+  // refuse) via SelectionNotify
+  async _answer(ev) {
+    const entry = 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) {
-        // x11 >= 3.4 encodes a number array at the property's declared
-        // format, so this reaches the requestor as three CARD32 atoms
-        X.ChangeProperty(0, ev.requestor, property, X.atoms.ATOM, 32, [
-          a.TARGETS,
-          a.UTF8_STRING,
-          X.atoms.STRING
-        ]);
-      } 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;
+    let served = false;
+    try {
+      if (entry) {
+        served =
+          ev.target === this._atoms.MULTIPLE
+            ? await this._serveMultiple(ev, entry, property)
+            : await this._serveTarget(ev.requestor, property, ev.target, entry);
       }
-      // mask 0: SelectionNotify is addressed to the requestor itself, so it
-      // goes to the client that created that window rather than to whoever
-      // selected events on it (ICCCM 2.2)
-      X.SendEvent(ev.requestor, 0, 0, {
+      // entry undefined: raced with a SelectionClear we haven't seen yet
+    } catch {
+      served = false; // refuse rather than leave the requestor waiting
+    }
+    if (!served) property = 0;
+    // mask 0: SelectionNotify is addressed to the requestor itself, so it
+    // goes to the client that created that window rather than to whoever
+    // selected events on it (ICCCM 2.2)
+    this._send(() =>
+      this.X.SendEvent(ev.requestor, 0, 0, {
         name: 'SelectionNotify',
         time: ev.time,
         requestor: ev.requestor,
         selection: ev.selection,
         target: ev.target,
         property
+      })
+    );
+  }
+
+  // convert one target into one property on the requestor's window;
+  // false means "cannot convert", which the caller turns into a refusal
+  async _serveTarget(requestor, property, target, entry) {
+    const X = this.X;
+    const a = this._atoms;
+    if (target === a.TARGETS) {
+      // x11 >= 3.4 encodes a number array at the property's declared
+      // format, so this reaches the requestor as CARD32 atoms
+      this._send(() =>
+        X.ChangeProperty(0, requestor, property, X.atoms.ATOM, 32, [
+          a.TARGETS,
+          a.TIMESTAMP,
+          a.MULTIPLE,
+          ...entry.targets.keys()
+        ])
+      );
+      return true;
+    }
+    if (target === a.TIMESTAMP) {
+      // ICCCM 2.6.2: the timestamp this selection was acquired with, as an
+      // INTEGER — Xt-based requestors ask for it before anything else
+      this._send(() => X.ChangeProperty(0, requestor, property, X.atoms.INTEGER, 32, [entry.time]));
+      return true;
+    }
+    // MULTIPLE inside MULTIPLE is not allowed, and a bare MULTIPLE never
+    // reaches here (its own branch runs first)
+    if (target === a.MULTIPLE) return false;
+    const value = entry.targets.get(target);
+    if (!value) return false;
+    if (value.data.length > this._limit()) {
+      await this._startIncr(requestor, property, value);
+      return true;
+    }
+    this._send(() =>
+      X.ChangeProperty(0, requestor, property, value.type, value.format, value.data)
+    );
+    return true;
+  }
+
+  // MULTIPLE (ICCCM 2.6.2): the requestor left a list of (target, property)
+  // pairs on its own window; convert each one and hand the list back with
+  // None in place of the properties we could not fill.
+  async _serveMultiple(ev, entry, property) {
+    const pairs = await this._getProperty(property, ev.requestor, 0);
+    // the list is defined as ATOM_PAIR, but requestors have been known to
+    // label it otherwise: what matters is that it decodes as 32-bit pairs
+    if (!pairs || pairs.format !== 32 || !pairs.data.length || pairs.data.length % 8) return false;
+    const list = Buffer.from(pairs.data);
+    let refused = false;
+    for (let o = 0; o < list.length; o += 8) {
+      const target = list.readUInt32LE(o);
+      const prop = list.readUInt32LE(o + 4);
+      if (!prop) continue; // already None
+      if (!(await this._serveTarget(ev.requestor, prop, target, entry))) {
+        list.writeUInt32LE(0, o + 4);
+        refused = true;
+      }
+    }
+    if (refused) {
+      const type = pairs.type || this._atoms.ATOM_PAIR;
+      this._send(() => this.X.ChangeProperty(0, ev.requestor, property, type, 32, list));
+    }
+    return true;
+  }
+
+  // ---- INCR, owner side (ICCCM 2.7.2): the mirror of _fetchProperty ----
+
+  // Answer the conversion with an INCR property holding a lower bound on
+  // the byte count; the requestor deleting that property starts the chunks.
+  async _startIncr(requestor, property, value) {
+    const key = `${requestor}:${property}`;
+    this._endTransfer(key); // a new conversion supersedes an unfinished one
+    await this._watch(requestor);
+    const transfer = {
+      key,
+      requestor,
+      property,
+      type: value.type,
+      format: value.format,
+      data: value.data,
+      offset: 0,
+      terminated: false,
+      timer: null
+    };
+    this._transfers.set(key, transfer);
+    this._touch(transfer);
+    this._send(() =>
+      this.X.ChangeProperty(0, requestor, property, this._atoms.INCR, 32, [value.data.length])
+    );
+  }
+
+  _onChunkConsumed(ev) {
+    const transfer = this._transfers.get(`${ev.wid}:${ev.atom}`);
+    if (!transfer) return;
+    if (transfer.terminated) {
+      // the zero-length property that ended the transfer has been read
+      this._endTransfer(transfer.key);
+      return;
+    }
+    const chunk = transfer.data.subarray(transfer.offset, transfer.offset + this._limit());
+    transfer.offset += chunk.length;
+    // an empty chunk is the end marker, not a chunk
+    if (chunk.length === 0) transfer.terminated = true;
+    this._touch(transfer);
+    this._send(() =>
+      this.X.ChangeProperty(
+        0,
+        transfer.requestor,
+        transfer.property,
+        transfer.type,
+        transfer.format,
+        chunk
+      )
+    );
+  }
+
+  _touch(transfer) {
+    clearTimeout(transfer.timer);
+    transfer.timer = setTimeout(() => this._endTransfer(transfer.key), this._incrTimeout);
+    transfer.timer.unref?.();
+  }
+
+  _endTransfer(key) {
+    const transfer = this._transfers.get(key);
+    if (!transfer) return;
+    clearTimeout(transfer.timer);
+    this._transfers.delete(key);
+    this._unwatch(transfer.requestor);
+  }
+
+  // PropertyNotify on the requestor's window is how the chunks are paced.
+  // Event masks are per-client, so ours is ours to set — but restore what
+  // we found: with a self-paste the requestor is our own helper window,
+  // whose PropertyChange the read path depends on.
+  async _watch(requestor) {
+    let watch = this._watched.get(requestor);
+    if (!watch) {
+      // register before the round trip, not after it: ICCCM lets a
+      // requestor run several conversions at once (on distinct properties),
+      // and those must share one watch rather than race to install it
+      watch = { count: 0, mask: 0 };
+      watch.ready = new Promise((resolve, reject) =>
+        this.X.GetWindowAttributes(requestor, (err, attrs) =>
+          err ? reject(err) : resolve(attrs.myEventMasks)
+        )
+      ).then((mask) => {
+        watch.mask = mask;
+        if (mask & x11.eventMask.PropertyChange) return;
+        this._send(() =>
+          this.X.ChangeWindowAttributes(
+            requestor,
+            { eventMask: mask | x11.eventMask.PropertyChange },
+            () => true
+          )
+        );
       });
-    });
+      this._watched.set(requestor, watch);
+    }
+    watch.count++;
+    try {
+      await watch.ready;
+    } catch (err) {
+      this._unwatch(requestor); // the requestor is gone; do not keep its entry
+      throw err;
+    }
   }
 
+  _unwatch(requestor) {
+    const watch = this._watched.get(requestor);
+    if (!watch || --watch.count > 0) return;
+    this._watched.delete(requestor);
+    if (watch.mask & x11.eventMask.PropertyChange) return;
+    // () => true swallows the BadWindow of a requestor that destroyed its
+    // window as soon as the paste completed — the usual ending
+    this._send(() =>
+      this.X.ChangeWindowAttributes(requestor, { eventMask: watch.mask }, () => true)
+    );
+  }
+
+  // ---- INCR, requestor side ----
+
   // ConvertSelection and wait for the owner's SelectionNotify answer
   _convert(sel, target, prop, selectionName, timeout) {
     return new Promise((resolve, reject) => {
@@ -236,11 +738,11 @@ export default class Clipboard {
     });
   }
 
-  _getProperty(prop) {
+  _getProperty(prop, wid = this._window.id, del = 1) {
     // 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) =>
+      this.X.GetProperty(del, wid, prop, 0, 0, 0x1fffffff, (err, res) =>
         err ? reject(err) : resolve(res)
       )
     );