ntk 4.0.0 → 4.1.0

package/lib/window.js

@@ -1,10 +1,10 @@
-import keysym from 'keysym';
 import x11 from 'x11';
 
 import { safeRelease } from './cleanup.js';
 import Drawable from './drawable.js';
 import Pixmap from './pixmap.js';
 import * as xevents from './events_map.js';
+import { decodeKey } from './keyboard.js';
 
 /**
  * How many rectangles a frame's dirty region is allowed to hold.
@@ -135,6 +135,125 @@ const forwardedXAttributes = [
   'cursor'
 ];
 
+// ICCCM 4.1.2.3 WM_NORMAL_HINTS flags. The first four say who chose the
+// window's geometry — without one of them a window manager is free to place
+// the window wherever it likes, whatever x/y it was created with.
+const SIZE_HINT = {
+  USPosition: 1,
+  USSize: 2,
+  PPosition: 4,
+  PSize: 8,
+  PMinSize: 16,
+  PMaxSize: 32,
+  PResizeInc: 64,
+  PAspect: 128,
+  PBaseSize: 256,
+  PWinGravity: 512
+};
+
+// ICCCM 4.1.2.4 WM_HINTS flags. MessageHint (128) is obsolete and unused.
+const WM_HINT = {
+  Input: 1,
+  State: 2,
+  IconPixmap: 4,
+  IconWindow: 8,
+  IconPosition: 16,
+  IconMask: 32,
+  WindowGroup: 64,
+  Urgency: 256
+};
+
+const SIZE_HINT_KEYS = new Set([
+  'minWidth', 'minHeight', 'maxWidth', 'maxHeight',
+  'widthInc', 'heightInc', 'baseWidth', 'baseHeight',
+  'minAspect', 'maxAspect', 'gravity', 'resizable',
+  'position', 'size', 'x', 'y', 'width', 'height'
+]);
+
+const WM_HINT_KEYS = new Set([
+  'input', 'initialState', 'urgent', 'icon', 'iconPixmap',
+  'iconMask', 'iconWindow', 'iconX', 'iconY', 'windowGroup'
+]);
+
+// Hint keys `createWindow` also accepts at the top level, per the API sketch
+// in ntk#19. x/y/width/height are deliberately absent: at the top level they
+// are the window's geometry, and only inside a `hints`/`sizeHints` object do
+// they mean the WM_NORMAL_HINTS fields of the same name. `position`/`size`
+// are absent for the same reason — as bare creation arguments they read as
+// geometry rather than as "who chose it".
+const CREATION_HINT_KEYS = [
+  ...[...SIZE_HINT_KEYS].filter(
+    (k) => !['x', 'y', 'width', 'height', 'position', 'size', 'resizable'].includes(k)
+  ),
+  ...WM_HINT_KEYS,
+  'transientFor',
+  'protocols'
+];
+
+// EWMH 5.7 _NET_WM_STATE, in spec order. FOCUSED and HIDDEN are set by the
+// window manager rather than asked for, but a client still reads them.
+const EWMH_STATES = [
+  'modal',
+  'sticky',
+  'maximized_vert',
+  'maximized_horz',
+  'shaded',
+  'skip_taskbar',
+  'skip_pager',
+  'hidden',
+  'fullscreen',
+  'above',
+  'below',
+  'demands_attention',
+  'focused'
+];
+
+/** 'fullscreen' -> '_NET_WM_STATE_FULLSCREEN'; a full atom name passes through. */
+function stateAtomName(name) {
+  return name.startsWith('_NET_WM_STATE_') ? name : `_NET_WM_STATE_${name.toUpperCase()}`;
+}
+
+/** The inverse, for reporting what the window manager put on the window. */
+function stateShortName(atomName) {
+  return atomName.startsWith('_NET_WM_STATE_')
+    ? atomName.slice('_NET_WM_STATE_'.length).toLowerCase()
+    : atomName;
+}
+
+/**
+ * Normalize the argument of setWmState.
+ *
+ * 'maximized' is the one name that is not an atom: EWMH maximizes an axis at
+ * a time, and giving the message both atoms at once is exactly what its two
+ * state slots are for.
+ */
+function expandStateNames(names) {
+  const list = Array.isArray(names) ? names : [names];
+  return list.flatMap((n) =>
+    n === 'maximized' ? ['maximized_vert', 'maximized_horz'] : [n]
+  );
+}
+
+/**
+ * Warn once per process about a hint that will do nothing.
+ *
+ * These mistakes are silent everywhere else: the server stores whatever
+ * property bytes it is handed, and only a window manager could tell that
+ * what it read means nothing. Same shape as node-x11's ChangeProperty
+ * warning, so a caller who gets it wrong on every window hears it once.
+ */
+const warnedHints = new Set();
+function warnHint(key, message) {
+  if (warnedHints.has(key)) return;
+  warnedHints.add(key);
+  console.warn(`ntk: ${message} Further occurrences are not reported.`);
+}
+
+/** A Window, a Pixmap, or a bare XID — all of these name a server resource. */
+function resourceId(value) {
+  return typeof value === 'number' ? value : (value?.id ?? 0);
+}
+
 /**
  * Turn a GetProperty reply into the shape the caller asked for. X property
  * types are atoms, so the only distinction we can make without a round trip
@@ -191,6 +310,17 @@ export default class Window extends Drawable {
     this._mapped = false;
     this._destroyed = false;
     this._titleSerial = 0;
+    this._overrideRedirect = !!args.overrideRedirect;
+    // WM_PROTOCOLS is a set: read-modify-write, serialized (see addProtocol)
+    this._protocols = null;
+    this._protocolQueue = Promise.resolve();
+    // so is _NET_WM_STATE, on the unmapped path (see setWmState)
+    this._wmStateQueue = Promise.resolve();
+    this._netWmStateAtom = 0; // resolved when a 'statechange' listener appears
+    // what setHints has accumulated per struct, so a later call can rewrite
+    // the whole property without dropping what an earlier one set
+    this._sizeHints = null;
+    this._wmHints = null;
     this._readyPromiseResolve = null;
     this._readyPromise = new Promise((resolve) => {
       this._readyPromiseResolve = resolve;
@@ -302,8 +432,23 @@ export default class Window extends Drawable {
     if (args.windowType) {
       this.setWindowType(args.windowType);
     }
-    if (args.sizeHints || args.resizable === false) {
-      this.setSizeHints({ ...args.sizeHints, ...(args.resizable === false && { resizable: false }) });
+    // ICCCM/EWMH hints at creation: `hints: { ... }`, the `sizeHints`/
+    // `resizable` arguments that predate it, or the hint names on their own
+    // at the top level. All of them land in one setHints call so that a
+    // window created with `minWidth` and a `hints` block writes
+    // WM_NORMAL_HINTS once, with both.
+    const hints = { ...args.sizeHints, ...args.hints };
+    if (args.resizable !== undefined) hints.resizable = args.resizable;
+    for (const key of CREATION_HINT_KEYS) {
+      if (args[key] !== undefined) hints[key] = args[key];
+    }
+    if (Object.keys(hints).length) {
+      this.setHints(hints);
+    }
+    // EWMH wants a pid and a client machine on top-level windows; child
+    // windows are an implementation detail nothing asks about
+    if (!args.id && args.pid !== false && parentId === app.display.screen[0].root) {
+      this.setPid(typeof args.pid === 'number' ? args.pid : undefined);
     }
     if (args.alwaysOnTop) {
       this.setAlwaysOnTop(true);
@@ -330,23 +475,32 @@ export default class Window extends Drawable {
         this._handleExpose(ev);
         return;
       }
-      // TODO cleanup
-      // also it seems that in keysym module not all keys have valid unicode values
-      if (eventName === 'keydown') {
-        const evKeysym = X.keycode2keysyms[ev.keycode];
-        const shift = ev.buttons & 1;
-        const capsLock = ev.buttons & 2;
-        const capital = (capsLock && !shift) || (shift && !capsLock);
-        const symInd = capital ? 1 : 0; // TODO: AltGr & other modifiers to use syms 2, 3, 4 etc
-        const entry = evKeysym && keysym.fromKeysym(evKeysym[symInd]);
-        if (entry) {
-          ev.codepoint = entry.unicode;
+      if (eventName === 'keydown' || eventName === 'keyup') {
+        // the active layout arrives in the event's own state bits, not in the
+        // keymap — see lib/keyboard.js. Keys that type nothing (arrows,
+        // F-keys, modifiers) leave `codepoint` absent rather than reporting 0.
+        const key = decodeKey(X.keycode2keysyms[ev.keycode], ev.buttons);
+        if (key) {
+          ev.keysym = key.keysym;
+          ev.baseKeysym = key.baseKeysym;
+          ev.group = key.group;
+          if (key.codepoint !== undefined) ev.codepoint = key.codepoint;
         }
       }
       if (this._coalesce && xevents.coalesce[eventName]) {
         this._enqueueCoalesced(eventName, ntkev);
         return;
       }
+      // the window manager reporting what it did with the window: a user who
+      // hit maximize or a fullscreen hotkey changes the state behind the
+      // app's back, and this is the only way an app that mirrors it in its
+      // own UI stays honest
+      if (eventName === 'property' && ev.atom === this._netWmStateAtom) {
+        this.getWmStates().then(
+          (states) => this.emit('statechange', states),
+          () => {}
+        );
+      }
       // deliver buffered state events before a discrete one so handlers see
       // them in the order they happened (a drag sees the move, then the up)
       this._flushCoalesced();
@@ -373,6 +527,16 @@ export default class Window extends Drawable {
     });
 
     this.on('newListener', (name) => {
+      // 'statechange' is derived from a PropertyNotify, so it needs the atom
+      // to compare against as well as the mask the table below selects
+      if (name === 'statechange' && !this._netWmStateAtom) {
+        this.atom('_NET_WM_STATE').then(
+          (atom) => {
+            this._netWmStateAtom = atom;
+          },
+          () => {}
+        );
+      }
       // extend the server-side event mask if this event needs it
       const eventMask = xevents.mask[name];
       if (!eventMask) return;
@@ -876,16 +1040,25 @@ export default class Window extends Drawable {
   }
 
   /**
-   * ICCCM WM_NORMAL_HINTS — how the window manager may resize this window.
+   * ICCCM WM_NORMAL_HINTS — how the window manager may size and place this
+   * window.
    *
    *   setSizeHints({ minWidth, minHeight, maxWidth, maxHeight,
    *                  widthInc, heightInc, baseWidth, baseHeight,
    *                  minAspect: [num, den], maxAspect: [num, den],
-   *                  gravity })
+   *                  gravity, position, size, resizable })
    *
    * `resizable: false` is shorthand for pinning min and max to the current
    * size. Without this property a WM lets the user resize a window to any
    * size at all, which is why fixed-size dialogs need it.
+   *
+   * `position` and `size` are `'user'` or `'program'` and declare who chose
+   * the geometry — a window manager that sees neither is free to place the
+   * window wherever its own policy says, whatever x/y it was created with.
+   * Passing `x`/`y` or `width`/`height` here implies `'program'`.
+   *
+   * This writes the whole struct: hints not passed are not carried over from
+   * an earlier call. `setHints()` is the accumulating form.
    */
   setSizeHints(hints = {}) {
     const {
@@ -900,8 +1073,13 @@ export default class Window extends Drawable {
       minAspect,
       maxAspect,
       gravity,
-      resizable
+      resizable,
+      x,
+      y,
+      width,
+      height
     } = hints;
+    let { position, size } = hints;
 
     let minW = minWidth;
     let minH = minHeight;
@@ -913,50 +1091,75 @@ export default class Window extends Drawable {
       maxW = maxW ?? this.width;
       maxH = maxH ?? this.height;
     }
+    // naming a geometry here is itself the statement that the program chose
+    // it; the flag is what carries that, and the fields alone are obsolete
+    if (position === undefined && (x !== undefined || y !== undefined)) position = 'program';
+    if (size === undefined && (width !== undefined || height !== undefined)) size = 'program';
 
     // XSizeHints: 18 CARD32s, flags first (ICCCM 4.1.2.3)
-    const PMinSize = 16;
-    const PMaxSize = 32;
-    const PResizeInc = 64;
-    const PAspect = 128;
-    const PBaseSize = 256;
-    const PWinGravity = 512;
-
     const v = new Uint32Array(18);
     let flags = 0;
+    if (position) {
+      flags |= position === 'user' ? SIZE_HINT.USPosition : SIZE_HINT.PPosition;
+      v[1] = x ?? this.x ?? 0;
+      v[2] = y ?? this.y ?? 0;
+    }
+    if (size) {
+      flags |= size === 'user' ? SIZE_HINT.USSize : SIZE_HINT.PSize;
+      v[3] = width ?? this.width ?? 0;
+      v[4] = height ?? this.height ?? 0;
+    }
     if (minW !== undefined || minH !== undefined) {
-      flags |= PMinSize;
+      flags |= SIZE_HINT.PMinSize;
       v[5] = minW ?? 0;
       v[6] = minH ?? 0;
     }
     if (maxW !== undefined || maxH !== undefined) {
-      flags |= PMaxSize;
+      flags |= SIZE_HINT.PMaxSize;
       v[7] = maxW ?? 0;
       v[8] = maxH ?? 0;
     }
     if (widthInc !== undefined || heightInc !== undefined) {
-      flags |= PResizeInc;
+      flags |= SIZE_HINT.PResizeInc;
       v[9] = widthInc ?? 1;
       v[10] = heightInc ?? 1;
     }
     if (minAspect || maxAspect) {
-      flags |= PAspect;
+      flags |= SIZE_HINT.PAspect;
       v[11] = minAspect?.[0] ?? 0;
       v[12] = minAspect?.[1] ?? 1;
       v[13] = maxAspect?.[0] ?? 0;
       v[14] = maxAspect?.[1] ?? 1;
     }
     if (baseWidth !== undefined || baseHeight !== undefined) {
-      flags |= PBaseSize;
+      flags |= SIZE_HINT.PBaseSize;
       v[15] = baseWidth ?? 0;
       v[16] = baseHeight ?? 0;
     }
     if (gravity !== undefined) {
-      flags |= PWinGravity;
+      flags |= SIZE_HINT.PWinGravity;
       v[17] = gravity;
     }
     v[0] = flags;
 
+    if (flags === 0) {
+      // WM_NORMAL_HINTS with flags 0 is a legal property meaning "I declare
+      // nothing" — indistinguishable from never having written it, and
+      // reported by nobody. `resizable: true` legitimately means that, so it
+      // is the one silent case; anything else here is a typo or a key from
+      // the wrong hint struct.
+      const keys = Object.keys(hints);
+      const onlyResizable = keys.length === 1 && resizable === true;
+      if (!onlyResizable) {
+        warnHint(
+          'sizeHints-empty',
+          `setSizeHints({ ${keys.join(', ')} }) sets no WM_NORMAL_HINTS flag, so nothing was ` +
+            'written — a flags word of 0 declares nothing and no window manager reports it.'
+        );
+      }
+      return this;
+    }
+
     safeRelease(this.X, () => {
       this.X.ChangeProperty(
         0,
@@ -970,6 +1173,345 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * ICCCM WM_HINTS — what the window wants from the window manager beyond
+   * its geometry.
+   *
+   *   setWmHints({ input, initialState, urgent, icon, iconMask, iconWindow,
+   *                iconX, iconY, windowGroup })
+   *
+   * - `input` is the ICCCM 4.1.7 input model: true if the window expects the
+   *   window manager to give it the keyboard focus. Set it before relying on
+   *   focus at all — a window manager reading no input hint is entitled to
+   *   assume the window takes focus for itself.
+   * - `initialState` is `'normal'` or `'iconic'` — the state to start in,
+   *   read once, when the window is first mapped.
+   * - `urgent` is the attention flag: taskbars flash, some window managers
+   *   raise. Clear it when the user has looked.
+   * - `icon` (an ntk `Pixmap` or an XID) is the ICCCM icon pixmap, which is
+   *   the old 1-bit-or-depth-matched mechanism. Modern desktops prefer
+   *   EWMH `_NET_WM_ICON`; set both if you care about old window managers.
+   * - `windowGroup` names a window the others belong to — the group
+   *   `setTransientFor('root')` refers to.
+   *
+   * Like `setSizeHints`, this writes the whole struct rather than merging
+   * with what an earlier call set; `setHints()` is the accumulating form.
+   */
+  setWmHints(hints = {}) {
+    const {
+      input,
+      initialState,
+      urgent,
+      icon,
+      iconPixmap,
+      iconMask,
+      iconWindow,
+      iconX,
+      iconY,
+      windowGroup
+    } = hints;
+
+    // XWMHints: 9 CARD32s, flags first (ICCCM 4.1.2.4)
+    const v = new Uint32Array(9);
+    let flags = 0;
+    if (input !== undefined) {
+      flags |= WM_HINT.Input;
+      v[1] = input ? 1 : 0;
+    }
+    if (initialState !== undefined) {
+      flags |= WM_HINT.State;
+      // NormalState 1, IconicState 3 (ICCCM 4.1.2.4); the states between
+      // them were withdrawn from the spec
+      v[2] = initialState === 'iconic' ? 3 : initialState === 'normal' ? 1 : initialState;
+    }
+    const pixmap = iconPixmap ?? icon;
+    if (pixmap !== undefined) {
+      flags |= WM_HINT.IconPixmap;
+      v[3] = resourceId(pixmap);
+    }
+    if (iconWindow !== undefined) {
+      flags |= WM_HINT.IconWindow;
+      v[4] = resourceId(iconWindow);
+    }
+    if (iconX !== undefined || iconY !== undefined) {
+      flags |= WM_HINT.IconPosition;
+      v[5] = iconX ?? 0;
+      v[6] = iconY ?? 0;
+    }
+    if (iconMask !== undefined) {
+      flags |= WM_HINT.IconMask;
+      v[7] = resourceId(iconMask);
+    }
+    if (windowGroup !== undefined) {
+      flags |= WM_HINT.WindowGroup;
+      v[8] = resourceId(windowGroup);
+    }
+    if (urgent) flags |= WM_HINT.Urgency;
+    v[0] = flags;
+
+    // `urgent: false` is the one call that legitimately produces flags 0:
+    // clearing attention means rewriting the struct without the bit. So the
+    // test here is whether any key was understood, not whether a flag came
+    // out of it.
+    const keys = Object.keys(hints);
+    const understood = keys.filter((k) => WM_HINT_KEYS.has(k));
+    if (understood.length === 0) {
+      warnHint(
+        'wmHints-empty',
+        `setWmHints({ ${keys.join(', ')} }) recognises none of those keys, so no WM_HINTS was written.`
+      );
+      return this;
+    }
+
+    safeRelease(this.X, () => {
+      this.X.ChangeProperty(
+        0,
+        this.id,
+        this.X.atoms.WM_HINTS,
+        this.X.atoms.WM_HINTS,
+        32,
+        Buffer.from(v.buffer, v.byteOffset, v.byteLength)
+      );
+    });
+    return this;
+  }
+
+  /**
+   * ICCCM WM_TRANSIENT_FOR — the window this one belongs to. It is what
+   * makes a second top-level window a *dialog* rather than an unrelated
+   * application window: the window manager stacks it above its owner, keeps
+   * it out of the taskbar and pager, iconifies it alongside, places it
+   * relative to the owner and gives it a dialog's reduced frame.
+   *
+   * Accepts a `Window`, an XID, `'root'` (transient for the whole window
+   * group — see `setWmHints({ windowGroup })`), or `null` to clear.
+   *
+   * Both atoms involved are predefined, so this needs no round trip and is
+   * on the wire before a `map()` on the next line — which is what ICCCM
+   * 4.1.2.6 expects, since a window manager may read the property only when
+   * the transient is mapped.
+   *
+   * Related but not the same as `setWindowType('dialog')`: this names *which*
+   * window is the owner, the type says *what kind* of window this is. EWMH
+   * treats a managed window with WM_TRANSIENT_FOR and no `_NET_WM_WINDOW_TYPE`
+   * as a dialog, but setting any type at all turns that fallback off — so
+   * real toolkits set both.
+   */
+  setTransientFor(owner) {
+    const X = this.X;
+    if (owner == null) {
+      safeRelease(X, () => X.DeleteProperty(this.id, X.atoms.WM_TRANSIENT_FOR));
+      return this;
+    }
+    const id = owner === 'root' ? this.app.display.screen[0].root : resourceId(owner);
+    if (this._overrideRedirect) {
+      // ICCCM 4.1.2.6 contrasts the two mechanisms: this property is for
+      // windows the WM manages, and an override-redirect window is never
+      // managed, so the property just sits there
+      warnHint(
+        'transient-override-redirect',
+        'setTransientFor on an override-redirect window has no effect — the window manager ' +
+          'never sees the window, so nothing reads the property.'
+      );
+    }
+    safeRelease(X, () => {
+      X.ChangeProperty(0, this.id, X.atoms.WM_TRANSIENT_FOR, X.atoms.WINDOW, 32, [id]);
+    });
+    return this;
+  }
+
+  /** The XID in WM_TRANSIENT_FOR, or null. The read side, for WM helpers. */
+  async getTransientFor() {
+    const v = await this.getProperty('WM_TRANSIENT_FOR', { as: 'numbers' }).catch(() => null);
+    return v && v.length ? v[0] : null;
+  }
+
+  /**
+   * ICCCM WM_PROTOCOLS — the messages this window is willing to receive, by
+   * atom name: `'WM_DELETE_WINDOW'`, `'WM_TAKE_FOCUS'`, `'_NET_WM_PING'`,
+   * `'_NET_WM_SYNC_REQUEST'`. Each arrives as a `'message'` event.
+   *
+   * Replaces the whole list. `addProtocol`/`removeProtocol` are the
+   * accumulating forms, and the ones to reach for: the property is a *set*,
+   * and a plain write of one atom silently drops the rest.
+   *
+   * @returns {Promise<Window>}
+   */
+  async setProtocols(names) {
+    const list = (Array.isArray(names) ? names : [names]).filter(Boolean);
+    const atoms = await Promise.all(list.map((n) => this.atom(n)));
+    this._protocols = new Set(atoms);
+    return this._writeProtocols();
+  }
+
+  /**
+   * Add one protocol to WM_PROTOCOLS, keeping the ones already there.
+   * @returns {Promise<Window>}
+   */
+  addProtocol(name) {
+    return this._changeProtocols(name, true);
+  }
+
+  /** Remove one protocol from WM_PROTOCOLS. @returns {Promise<Window>} */
+  removeProtocol(name) {
+    return this._changeProtocols(name, false);
+  }
+
+  /** The atom names in WM_PROTOCOLS. @returns {Promise<string[]>} */
+  async getProtocols() {
+    const atoms = await this.getProperty('WM_PROTOCOLS', { as: 'numbers' }).catch(() => null);
+    if (!atoms || !atoms.length) return [];
+    return Promise.all(
+      atoms.map(
+        (a) =>
+          new Promise((resolve) => this.X.GetAtomName(a, (err, name) => resolve(err ? null : name)))
+      )
+    ).then((names) => names.filter(Boolean));
+  }
+
+  /**
+   * Read-modify-write on the atom set, serialized.
+   *
+   * Two adds in the same tick would otherwise each read the list before the
+   * other wrote it, and the second would drop the first — the same clobber
+   * this method exists to prevent, just harder to see.
+   */
+  _changeProtocols(name, add) {
+    const run = async () => {
+      const [current, atom] = await Promise.all([this._loadProtocols(), this.atom(name)]);
+      if (add) current.add(atom);
+      else current.delete(atom);
+      return this._writeProtocols();
+    };
+    this._protocolQueue = this._protocolQueue.then(run, run);
+    return this._protocolQueue;
+  }
+
+  /**
+   * The atom set as it stands on the server, read once.
+   *
+   * A window we created has none. A window adopted by id may already carry a
+   * list its own client wrote, and replacing that is exactly the bug.
+   */
+  async _loadProtocols() {
+    if (this._protocols) return this._protocols;
+    const current = await this.getProperty('WM_PROTOCOLS', { as: 'numbers' }).catch(() => null);
+    this._protocols = new Set(current || []);
+    return this._protocols;
+  }
+
+  async _writeProtocols() {
+    const property = await this.atom('WM_PROTOCOLS');
+    if (this._destroyed) return this;
+    const atoms = [...this._protocols];
+    safeRelease(this.X, () => {
+      this.X.ChangeProperty(0, this.id, property, this.X.atoms.ATOM, 32, atoms);
+    });
+    return this;
+  }
+
+  /**
+   * EWMH `_NET_WM_PID` and ICCCM `WM_CLIENT_MACHINE` — which process on
+   * which host owns this window. Together they are how a desktop offers to
+   * force-quit an unresponsive application, and how `xkill`-style tools name
+   * what they are about to kill; EWMH requires the machine for the pid to
+   * mean anything, so both are written or neither is.
+   *
+   * Top-level windows get this automatically; pass `pid: false` at creation
+   * to opt out. In a browser bundle there is no pid and no hostname, so the
+   * call does nothing.
+   */
+  setPid(pid, hostname) {
+    const proc = globalThis.process;
+    const id = pid ?? proc?.pid;
+    const host = hostname ?? Window._hostname();
+    if (id === undefined || !host) return this;
+    const X = this.X;
+    safeRelease(X, () => {
+      X.ChangeProperty(
+        0,
+        this.id,
+        X.atoms.WM_CLIENT_MACHINE,
+        X.atoms.STRING,
+        8,
+        Buffer.from(String(host), 'latin1')
+      );
+    });
+    return this._withAtoms(['_NET_WM_PID'], (atoms) => {
+      safeRelease(X, () => {
+        X.ChangeProperty(0, this.id, atoms._NET_WM_PID, X.atoms.CARDINAL, 32, [id]);
+      });
+    });
+  }
+
+  /** os.hostname(), looked up once, and absent in a browser bundle. */
+  static _hostname() {
+    if (Window._cachedHostname === undefined) {
+      const os = globalThis.process?.getBuiltinModule?.('node:os');
+      Window._cachedHostname = os?.hostname?.() ?? null;
+    }
+    return Window._cachedHostname;
+  }
+
+  /**
+   * Set window manager hints by name, across whichever properties they
+   * belong to, keeping the ones set before.
+   *
+   *   wnd.setHints({ transientFor: main, maxWidth: 900, urgent: true });
+   *
+   * Every key `setSizeHints` and `setWmHints` understand works here, plus
+   * `transientFor` and `protocols`. The same keys are accepted by
+   * `createWindow`, at the top level or under `hints`.
+   *
+   * The difference from calling the two setters directly is that this one
+   * remembers: each property is rewritten from everything set on this window
+   * so far, so `setHints({ urgent: true })` after `setHints({ input: true })`
+   * keeps the input hint. Those setters write their struct whole.
+   *
+   * Everything but `protocols` is on the wire when this returns — a
+   * `map()` on the next line cannot overtake it. `protocols` needs the atom
+   * interned first; await `setProtocols()` if the ordering matters.
+   */
+  setHints(hints = {}) {
+    const size = {};
+    const wm = {};
+    let sizeTouched = false;
+    let wmTouched = false;
+    const unknown = [];
+
+    for (const key of Object.keys(hints)) {
+      if (SIZE_HINT_KEYS.has(key)) {
+        size[key] = hints[key];
+        sizeTouched = true;
+      } else if (WM_HINT_KEYS.has(key)) {
+        wm[key] = hints[key];
+        wmTouched = true;
+      } else if (key !== 'transientFor' && key !== 'protocols') {
+        unknown.push(key);
+      }
+    }
+    if (unknown.length) {
+      warnHint(
+        `hints-unknown-${unknown.join(',')}`,
+        `setHints ignored unknown hint${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}.`
+      );
+    }
+
+    if (hints.transientFor !== undefined) this.setTransientFor(hints.transientFor);
+    if (sizeTouched) {
+      this._sizeHints = { ...this._sizeHints, ...size };
+      this.setSizeHints(this._sizeHints);
+    }
+    if (wmTouched) {
+      this._wmHints = { ...this._wmHints, ...wm };
+      this.setWmHints(this._wmHints);
+    }
+    if (hints.protocols !== undefined) {
+      this.setProtocols(hints.protocols).catch((err) => this.app.options.onXError?.(err));
+    }
+    return this;
+  }
+
   /**
    * ICCCM WM_CLASS — the instance/class pair taskbars and WMs use to group
    * windows, match icons and apply per-application rules. Two NUL-
@@ -1013,6 +1555,171 @@ export default class Window extends Drawable {
     });
   }
 
+  /**
+   * EWMH `_NET_WM_STATE` — fullscreen, maximized, sticky, skip-taskbar and
+   * the rest of the states a window can be in.
+   *
+   *   await wnd.setWmState('fullscreen');            // add, the default
+   *   await wnd.setWmState('maximized', 'add');      // both axes at once
+   *   await wnd.setWmState(['skip_taskbar', 'skip_pager'], 'add');
+   *   await wnd.setWmState('fullscreen', 'toggle');
+   *
+   * Names are the EWMH atoms without their `_NET_WM_STATE_` prefix, in
+   * lower case; full atom names work too. `'maximized'` expands to the
+   * `MAXIMIZED_VERT` + `MAXIMIZED_HORZ` pair, which is why the spec allows
+   * two states per message.
+   *
+   * How the change is made depends on whether the window is mapped, and the
+   * two are not interchangeable (EWMH 7.7): a mapped window *asks* the
+   * window manager with a ClientMessage to the root, an unmapped one
+   * *declares* its initial state by writing the property. This asks the
+   * server which it is rather than trusting the last map/unmap event, so it
+   * is right even on the line after `map()`.
+   *
+   * @param {string|string[]} names
+   * @param {'add'|'remove'|'toggle'} [action]
+   * @returns {Promise<boolean>} whether the window manager advertises every
+   *   state asked for in `_NET_SUPPORTED`. The request is made either way —
+   *   an unmapped window may legitimately declare a state before any window
+   *   manager is running — but `false` means nothing is listening for it.
+   */
+  async setWmState(names, action = 'add') {
+    const list = expandStateNames(names);
+    if (!list.length) return false;
+    if (list.length > 2) {
+      // EWMH gives the message two atom slots and no more; splitting into
+      // several messages is fine, but silently sending the first two is not
+      throw new RangeError(
+        `setWmState: a _NET_WM_STATE message carries at most 2 states, got ${list.length}`
+      );
+    }
+    const mode = { remove: 0, add: 1, toggle: 2 }[action];
+    if (mode === undefined) {
+      throw new TypeError(`setWmState: action must be add, remove or toggle, got ${action}`);
+    }
+
+    const [atoms, supported, attrs] = await Promise.all([
+      this._stateAtoms(list),
+      this._netSupported(),
+      this.getAttributes().catch(() => null)
+    ]);
+    if (this._destroyed) return false;
+    const ids = list.map((n) => atoms.get(n));
+    // mapState: 0 Unmapped, 1 Unviewable, 2 Viewable. Unviewable is mapped
+    // under an unmapped ancestor, which is still mapped as far as EWMH cares
+    const mapped = attrs ? attrs.mapState !== 0 : this._mapped;
+
+    if (mapped) {
+      const root = this.app.display.screen[0].root;
+      const messageType = await this.atom('_NET_WM_STATE');
+      if (this._destroyed) return false;
+      safeRelease(this.X, () => {
+        this.X.SendClientMessage(root, this.id, messageType, 32, [
+          mode,
+          ids[0],
+          ids[1] ?? 0,
+          1 // source indication: a normal application, not a pager
+        ]);
+      });
+    } else {
+      await this._writeWmState(ids, mode);
+    }
+    return ids.every((id) => supported.has(id));
+  }
+
+  /** `setWmState(names, 'add')`. @returns {Promise<boolean>} */
+  addWmState(names) {
+    return this.setWmState(names, 'add');
+  }
+
+  /** `setWmState(names, 'remove')`. @returns {Promise<boolean>} */
+  removeWmState(names) {
+    return this.setWmState(names, 'remove');
+  }
+
+  /**
+   * The states currently in `_NET_WM_STATE`, as short lower-case names.
+   * `[]` when the window has none.
+   *
+   * This is what the window manager put there, so it is the answer to "am I
+   * actually fullscreen", where `setWmState` is only the request.
+   *
+   * @returns {Promise<string[]>}
+   */
+  async getWmStates() {
+    const ids = await this.getProperty('_NET_WM_STATE', { as: 'numbers' }).catch(() => null);
+    if (!ids || !ids.length) return [];
+    const known = await this._stateAtoms(EWMH_STATES);
+    const byAtom = new Map([...known].map(([name, atom]) => [atom, name]));
+    return Promise.all(
+      ids.map(async (id) => {
+        const name = byAtom.get(id);
+        if (name) return name;
+        // a state this build does not know about, or a vendor one
+        const full = await new Promise((resolve) =>
+          this.X.GetAtomName(id, (err, n) => resolve(err ? null : n))
+        );
+        return full ? stateShortName(full) : null;
+      })
+    ).then((names) => names.filter(Boolean));
+  }
+
+  /**
+   * Read-modify-write on the atom list an unmapped window declares.
+   *
+   * `_NET_WM_STATE` is a list, so a plain Replace with one atom drops the
+   * rest — the same trap WM_PROTOCOLS had. Serialized for the same reason:
+   * two changes in a tick would each read the list before the other wrote.
+   */
+  _writeWmState(ids, mode) {
+    const run = async () => {
+      const current = new Set(
+        (await this.getProperty('_NET_WM_STATE', { as: 'numbers' }).catch(() => null)) || []
+      );
+      for (const id of ids) {
+        const add = mode === 2 ? !current.has(id) : mode === 1;
+        if (add) current.add(id);
+        else current.delete(id);
+      }
+      const property = await this.atom('_NET_WM_STATE');
+      if (this._destroyed) return this;
+      safeRelease(this.X, () => {
+        this.X.ChangeProperty(0, this.id, property, this.X.atoms.ATOM, 32, [...current]);
+      });
+      return this;
+    };
+    this._wmStateQueue = this._wmStateQueue.then(run, run);
+    return this._wmStateQueue;
+  }
+
+  /** Intern the atoms for a list of short state names. @returns {Promise<Map>} */
+  async _stateAtoms(names) {
+    const ids = await Promise.all(names.map((n) => this.atom(stateAtomName(n))));
+    return new Map(names.map((n, i) => [n, ids[i]]));
+  }
+
+  /**
+   * The atoms in the root window's `_NET_SUPPORTED`, read once per
+   * connection.
+   *
+   * It is one property on one window describing one window manager, so
+   * re-reading it per window per call is pure round trips. A window manager
+   * that restarts and advertises differently is the cost, and the same one
+   * every toolkit accepts.
+   *
+   * @returns {Promise<Set<number>>}
+   */
+  _netSupported() {
+    if (!this.app._netSupportedPromise) {
+      this.app._netSupportedPromise = this.app
+        .rootWindow()
+        .getProperty('_NET_SUPPORTED', { as: 'numbers' })
+        .then((ids) => new Set(ids || []))
+        .catch(() => new Set());
+    }
+    return this.app._netSupportedPromise;
+  }
+
   /**
    * Keep this window above normal windows.
    *
@@ -1024,50 +1731,12 @@ export default class Window extends Drawable {
    * parent is root — not our own id.
    */
   setAlwaysOnTop(on = true) {
-    const X = this.X;
-    const _NET_WM_STATE_ADD = 1;
-    const _NET_WM_STATE_REMOVE = 0;
-
-    this._withAtoms(['_NET_WM_STATE', '_NET_WM_STATE_ABOVE', '_NET_SUPPORTED'], (atoms) => {
-      const root = this.app.display.screen[0].root;
-      safeRelease(X, () => {
-        X.GetProperty(0, root, atoms._NET_SUPPORTED, X.atoms.ATOM, 0, 1024, (err, prop) => {
-          if (err || this._destroyed) return;
-          let supported = false;
-          const data = prop?.data;
-          for (let i = 0; data && i + 4 <= data.length; i += 4) {
-            if (data.readUInt32LE(i) === atoms._NET_WM_STATE_ABOVE) {
-              supported = true;
-              break;
-            }
-          }
-          if (supported) {
-            // a mapped window changes state by asking the WM, not by
-            // writing the property (EWMH 7.7). SendEvent takes raw event
-            // bytes, so pack the 32-byte ClientMessage by hand.
-            const ev = Buffer.alloc(32);
-            ev.writeUInt8(33, 0); // ClientMessage
-            ev.writeUInt8(32, 1); // format
-            ev.writeUInt32LE(this.id >>> 0, 4);
-            ev.writeUInt32LE(atoms._NET_WM_STATE >>> 0, 8);
-            ev.writeUInt32LE(on ? _NET_WM_STATE_ADD : _NET_WM_STATE_REMOVE, 12);
-            ev.writeUInt32LE(atoms._NET_WM_STATE_ABOVE >>> 0, 16);
-            ev.writeUInt32LE(0, 20); // second property: none
-            ev.writeUInt32LE(1, 24); // source indication: application
-            safeRelease(X, () => {
-              X.SendEvent(
-                root,
-                false,
-                x11.eventMask.SubstructureRedirect | x11.eventMask.SubstructureNotify,
-                ev
-              );
-            });
-          } else {
-            this._appleWMSetLevel(on);
-          }
-        });
-      });
-    });
+    this.setWmState('above', on ? 'add' : 'remove').then(
+      (supported) => {
+        if (!supported && !this._destroyed) this._appleWMSetLevel(on);
+      },
+      (err) => this.app.options.onXError?.(err)
+    );
     return this;
   }
 
@@ -1286,6 +1955,27 @@ export default class Window extends Drawable {
     return this;
   }
 
+  /**
+   * Remove a property.
+   *
+   * Not the same as writing an empty value, and not at all the same as
+   * writing a zero: a deleted property reads back as type None — which is
+   * how "this client never declared that" is spelled — and a window manager
+   * watching gets a PropertyNotify with state Delete. `setTransientFor(null)`
+   * goes through here for exactly that reason; a `WM_TRANSIENT_FOR` of 0
+   * would name window None as the owner rather than saying there is none.
+   *
+   * @returns {Promise<Window>}
+   */
+  async deleteProperty(name) {
+    const atom = await this.atom(name);
+    if (this._destroyed) return this;
+    safeRelease(this.X, () => {
+      this.X.DeleteProperty(this.id, atom);
+    });
+    return this;
+  }
+
   /**
    * Intern an atom by name. node-x11 caches them per connection, so asking
    * again for one already interned costs no round trip.
@@ -1310,16 +2000,27 @@ export default class Window extends Drawable {
 
   /**
    * WM_NORMAL_HINTS as an object shaped like setSizeHints' argument —
-   * `{ minWidth, minHeight, maxWidth, maxHeight, widthInc, heightInc,
-   * baseWidth, baseHeight, minAspect, maxAspect, gravity }`, each present
-   * only if the client set its flag. Resolves to `{}` when the window has
-   * no hints, so callers can destructure without a null check.
+   * `{ position, size, x, y, width, height, minWidth, minHeight, maxWidth,
+   * maxHeight, widthInc, heightInc, baseWidth, baseHeight, minAspect,
+   * maxAspect, gravity }`, each present only if the client set its flag.
+   * Resolves to `{}` when the window has no hints, so callers can
+   * destructure without a null check.
    */
   async getSizeHints() {
     const v = await this.getProperty('WM_NORMAL_HINTS', { as: 'numbers' }).catch(() => null);
     if (!v || v.length < 18) return {};
     const flags = v[0];
     const hints = {};
+    if (flags & (SIZE_HINT.USPosition | SIZE_HINT.PPosition)) {
+      hints.position = flags & SIZE_HINT.USPosition ? 'user' : 'program';
+      hints.x = v[1];
+      hints.y = v[2];
+    }
+    if (flags & (SIZE_HINT.USSize | SIZE_HINT.PSize)) {
+      hints.size = flags & SIZE_HINT.USSize ? 'user' : 'program';
+      hints.width = v[3];
+      hints.height = v[4];
+    }
     if (flags & 16) {
       hints.minWidth = v[5];
       hints.minHeight = v[6];
@@ -1344,6 +2045,30 @@ export default class Window extends Drawable {
     return hints;
   }
 
+  /**
+   * WM_HINTS as an object shaped like setWmHints' argument, each field
+   * present only if the client set its flag. `{}` when the window has none.
+   * `urgent` is reported whenever the property exists, since its absence is
+   * meaningful — it is what "the user has looked" looks like.
+   */
+  async getWmHints() {
+    const v = await this.getProperty('WM_HINTS', { as: 'numbers' }).catch(() => null);
+    if (!v || v.length < 9) return {};
+    const flags = v[0];
+    const hints = { urgent: !!(flags & WM_HINT.Urgency) };
+    if (flags & WM_HINT.Input) hints.input = !!v[1];
+    if (flags & WM_HINT.State) hints.initialState = v[2] === 3 ? 'iconic' : 'normal';
+    if (flags & WM_HINT.IconPixmap) hints.iconPixmap = v[3];
+    if (flags & WM_HINT.IconWindow) hints.iconWindow = v[4];
+    if (flags & WM_HINT.IconPosition) {
+      hints.iconX = v[5];
+      hints.iconY = v[6];
+    }
+    if (flags & WM_HINT.IconMask) hints.iconMask = v[7];
+    if (flags & WM_HINT.WindowGroup) hints.windowGroup = v[8];
+    return hints;
+  }
+
   /**
    * GetWindowAttributes — `{ mapState, overrideRedirect, ... }`. A window
    * manager adopting the windows that already existed when it started
@@ -1419,19 +2144,19 @@ export default class Window extends Drawable {
       height = this.height,
       borderWidth = 0
     } = geometry;
-    const ev = Buffer.alloc(32);
-    ev[0] = 22; // ConfigureNotify
-    ev.writeUInt32LE(this.id >>> 0, 4); // event window
-    ev.writeUInt32LE(this.id >>> 0, 8); // the window itself
-    ev.writeUInt32LE(0, 12); // above-sibling: None
-    ev.writeInt16LE(x, 16);
-    ev.writeInt16LE(y, 18);
-    ev.writeUInt16LE(width, 20);
-    ev.writeUInt16LE(height, 22);
-    ev.writeUInt16LE(borderWidth, 24);
-    ev[26] = 0; // override-redirect
     safeRelease(this.X, () =>
-      this.X.SendEvent(this.id, 0, x11.eventMask.StructureNotify, ev)
+      this.X.SendEvent(this.id, 0, x11.eventMask.StructureNotify, {
+        name: 'ConfigureNotify',
+        wid: this.id, // event window
+        wid1: this.id, // the window the event is about
+        aboveSibling: 0, // None: bottom of the stack
+        x,
+        y,
+        width,
+        height,
+        borderWidth,
+        overrideRedirect: 0
+      })
     );
     return this;
   }
@@ -1456,14 +2181,12 @@ export default class Window extends Drawable {
       return false;
     }
     const wmProtocols = await this.atom('WM_PROTOCOLS');
-    const ev = Buffer.alloc(32);
-    ev[0] = 33; // ClientMessage
-    ev[1] = 32; // format
-    ev.writeUInt32LE(this.id >>> 0, 4);
-    ev.writeUInt32LE(wmProtocols >>> 0, 8);
-    ev.writeUInt32LE(deleteAtom >>> 0, 12);
-    ev.writeUInt32LE(0, 16); // CurrentTime
-    safeRelease(this.X, () => this.X.SendEvent(this.id, 0, 0, ev));
+    // mask 0: deliver to the client that created the window, not to whoever
+    // selected events on it — a WM_PROTOCOLS message is addressed to the
+    // owner, so it must not go out with the EWMH substructure default
+    safeRelease(this.X, () =>
+      this.X.SendClientMessage(this.id, this.id, wmProtocols, 32, [deleteAtom, 0 /* CurrentTime */], 0)
+    );
     return true;
   }
 
@@ -1535,30 +2258,19 @@ export default class Window extends Drawable {
     return new Window(this.app, { parent: this, ...params });
   }
 
-  // opt in to the WM_DELETE_WINDOW protocol: the window manager sends a
-  // 'message' event instead of killing the connection when the user closes
-  // the window
+  /**
+   * Opt in to the WM_DELETE_WINDOW protocol: the window manager sends a
+   * 'message' event instead of killing the connection when the user closes
+   * the window.
+   *
+   * Kept for compatibility, and now an alias — it used to write
+   * WM_PROTOCOLS as a list of exactly one atom, so the next protocol added
+   * by any other means erased it. Prefer `addProtocol('WM_DELETE_WINDOW')`,
+   * which is awaitable.
+   */
   setActions() {
-    const X = this.X;
-    const wid = this.id;
-    // 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);
-            });
-          });
-        });
-      });
-    });
+    this.addProtocol('WM_DELETE_WINDOW').catch((err) => this.app.options.onXError?.(err));
+    return this;
   }
 
   destroy() {