ntk 6.7.0 → 7.1.0

package/lib/app.js

@@ -8,6 +8,50 @@ import { ShmUploader } from './shm-upload.js';
 import FontManager from './text/fontmanager.js';
 import Window from './window.js';
 
+/**
+ * The highest predefined atom id in the core protocol, `XA_WM_TRANSIENT_FOR`.
+ *
+ * Atoms 1 to 68 are named by the protocol itself, so every server agrees on
+ * them and no server ever frees them. Anything above is interned at runtime
+ * and belongs to the connection that asked for it — see `_isolateAtoms`.
+ */
+const PREDEFINED_ATOM_MAX = 68;
+
+/**
+ * Frame interval used before the display has been asked, in ms — and the one
+ * kept on a server that cannot answer.
+ */
+const DEFAULT_FRAME_INTERVAL = 16;
+
+/**
+ * The range a refresh rate has to fall in to be paced against, in Hz. Below
+ * this a display is not something a UI should be throttled to, and above it
+ * the numbers are not describing a display at all.
+ */
+const MIN_REFRESH_RATE = 20;
+const MAX_REFRESH_RATE = 1000;
+
+/**
+ * A RandR mode's vertical refresh rate in Hz, or 0 when it does not describe
+ * one.
+ *
+ * `dot_clock / (h_total * v_total)`, with the two flags that make a frame
+ * something other than one pass down the mode, exactly as xrandr computes it:
+ * an interlaced mode paints half the lines per pass, a doublescan mode paints
+ * each line twice.
+ *
+ * The zero check is not defensive: a virtual output has no pixel clock to
+ * report and Xvfb — which is what CI runs against — fills all three fields
+ * with zeroes, so the arithmetic yields NaN rather than a rate.
+ */
+function modeRate(mode) {
+  if (!mode || !mode.dot_clock || !mode.h_total || !mode.v_total) return 0;
+  let vTotal = mode.v_total;
+  if (mode.modeflags & 0x10) vTotal /= 2; // Interlace
+  if (mode.modeflags & 0x20) vTotal *= 2; // DoubleScan
+  return mode.dot_clock / (mode.h_total * vTotal);
+}
+
 /**
  * A connection to an X server. Owns the underlying node-x11 client
  * (`app.X`) and acts as a factory for windows and pixmaps.
@@ -41,6 +85,7 @@ export default class App {
     this.display = display;
     this.X = display.client;
     this.options = options;
+    this._isolateAtoms();
     this._fonts = null;
     this._clipboard = null;
     this._cursors = null;
@@ -59,6 +104,120 @@ export default class App {
     });
   }
 
+  /**
+   * Give this connection an atom table of its own.
+   *
+   * node-x11 hands every client the *same* table object — `this.atoms =
+   * stdatoms` in xcore, assigned rather than copied — and `InternAtom`
+   * answers out of it without a round trip when the name is already there.
+   * So an id interned on one connection is handed to every other connection
+   * in the process, which have never asked the server for it.
+   *
+   * That is safe only while something keeps the server alive. An X server
+   * frees every atom it holds when its **last** client disconnects, and
+   * hands the same ids out again to whatever is interned next. A process
+   * that opens connections in sequence — a test suite, a tool that runs a
+   * few apps, anything under Xvfb with no window manager holding the server
+   * open — therefore writes properties with ids the server has forgotten.
+   * The visible half of that is `BadAtom` on a `ChangeProperty` naming an
+   * atom the app never chose; the quiet half is worse, because once the id
+   * has been reissued to a different name the write lands under *that* atom
+   * and no error is reported at all.
+   *
+   * Keeping only the predefined atoms is what makes the copy correct: ids 1
+   * to 68 are fixed by the core protocol, identical on every server, and
+   * never freed. Everything above that has to be interned per connection,
+   * which now happens because this table starts without it. Within one
+   * connection the caching still works, and it is still correct, because a
+   * live connection is exactly what stops the server resetting.
+   */
+  _isolateAtoms() {
+    const shared = this.X.atoms;
+    if (!shared) return;
+    const own = {};
+    const names = {};
+    for (const [name, id] of Object.entries(shared)) {
+      if (id > PREDEFINED_ATOM_MAX) continue;
+      own[name] = id;
+      names[id] = name;
+    }
+    this.X.atoms = own;
+    this.X.atom_names = names;
+  }
+
+  /**
+   * The fastest refresh rate any active output is running at, in Hz, or
+   * `null` until the display has been asked — and on a server with no RandR
+   * or no mode worth pacing to.
+   *
+   * The fastest rather than the one this or that window is on, because what
+   * it feeds is a rate *ceiling* (see `frameInterval`), and a window paced
+   * faster than its own monitor is bounded by the next gate along rather than
+   * drawing more than anyone can see. Tracking which output every window
+   * overlaps would cost a per-window RandR lookup plus change tracking, to
+   * make a ceiling slightly tighter.
+   */
+  get refreshRate() {
+    if (this._refreshProbe === undefined) this._probeRefreshRate();
+    return this._refreshRate ?? null;
+  }
+
+  /**
+   * The frame interval windows on this connection take by default, in ms:
+   * the display's own period rather than a guess, so an animation loop on a
+   * 165Hz output is not held to the 62.5fps a hardcoded 16 implies. `null`
+   * until the probe has answered; windows created before then start on the
+   * default and adopt this when it lands.
+   *
+   * A window that presents takes its rate from the display directly and needs
+   * none of this — see docs/window.md "What ends a frame". This is what the
+   * fence clock paces to, which is every window on a server without Present,
+   * and every window before its first frames have been shown.
+   */
+  get frameInterval() {
+    const rate = this.refreshRate;
+    return rate ? 1000 / rate : null;
+  }
+
+  /**
+   * Ask RandR what the outputs are running at, once per connection, in the
+   * background.
+   *
+   * Not on the connect path: `createClient` is already four round trips deep
+   * and this is three more, for something no window needs before its first
+   * frame. Failures are silent by design — every one of them means "no rate
+   * to be had", which is exactly what the default covers.
+   */
+  _probeRefreshRate() {
+    this._refreshProbe = null; // in progress; only ever started once
+    const X = this.X;
+    X.require('randr', (err, R) => {
+      if (err || !R) return;
+      const root = this.display.screen[0].root;
+      R.GetScreenResourcesCurrent(root, (resourcesError, resources) => {
+        if (resourcesError || !resources?.crtcs?.length) return;
+        const modes = new Map(resources.modeinfos.map((mode) => [mode.id, mode]));
+        let pending = resources.crtcs.length;
+        let best = 0;
+        for (const crtc of resources.crtcs) {
+          R.GetCrtcInfo(crtc, resources.config_timestamp, (crtcError, info) => {
+            // a crtc with no mode is one that is switched off
+            if (!crtcError && info) best = Math.max(best, modeRate(modes.get(info.mode)));
+            if (--pending) return;
+            if (best < MIN_REFRESH_RATE || best > MAX_REFRESH_RATE) return;
+            this._refreshRate = best;
+            this._adoptFrameInterval(1000 / best);
+          });
+        }
+      });
+    });
+  }
+
+  /** hand the measured default to the windows that are still on the guess */
+  _adoptFrameInterval(ms) {
+    for (const wnd of Window._cacheFor(this).values()) wnd._adoptDefaultFrameInterval(ms);
+  }
+
   /** the text API entry point: font matching/loading, shaping, layout */
   get fonts() {
     if (!this._fonts) this._fonts = new FontManager({ source: this.options.fontSource });

package/lib/renderingcontext_2d.js

@@ -60,6 +60,23 @@ function intersectBox(a, b) {
 
 const DEFAULT_FONT = "20px sans-serif";
 
+// `"wght" 460, "wdth" 87.5` — the CSS grammar, quotes optional. An object is
+// passed through, so callers can skip the string entirely.
+const VARIATION_RE = /["']?([a-zA-Z0-9]{4})["']?\s+(-?[\d.]+)/g;
+
+function parseVariationSettings(val) {
+  if (!val || val === "normal") return null;
+  if (typeof val === "object") return val;
+  if (typeof val !== "string") return null;
+  const out = {};
+  let any = false;
+  for (const [, tag, value] of val.matchAll(VARIATION_RE)) {
+    out[tag] = Number(value);
+    any = true;
+  }
+  return any ? out : null;
+}
+
 /**
  * Fallback for a context dropped without `destroy()`, matching Pixmap,
  * Picture and GlyphSet. Only the GCs are freed here: everything else a
@@ -507,6 +524,7 @@ class RenderingContext2d {
       gco: this._gco,
       textStyle: this._textStyle,
       fontString: this._lastFontString,
+      fontVariations: this._fontVariations,
       textAlign: this.textAlign,
       textBaseline: this.textBaseline,
       m: this._m.slice(),
@@ -529,6 +547,7 @@ class RenderingContext2d {
     this._gco = s.gco;
     this._textStyle = s.textStyle;
     this._lastFontString = s.fontString;
+    this._fontVariations = s.fontVariations;
     this.textAlign = s.textAlign;
     this.textBaseline = s.textBaseline;
     this._m = s.m;
@@ -1710,10 +1729,10 @@ class RenderingContext2d {
    * Stroke fast path for a device-space box (from a roundRect tag or
    * strokeRect). Beyond the fill's conditions: uniform lineWidth, no
    * dashes — and the half-pixel one that matters: the stroke band must land
-   * on pixel boundaries. A 1px border drawn the correct way (path inset by
-   * bw/2, so the band [X, X+1] sits on integers) passes; a 1px stroke on
-   * integer path coordinates is genuinely a two-row 50% band and must keep
-   * falling back, because the fast path would not reproduce it.
+   * on pixel boundaries. A border drawn the correct way (path inset by bw/2,
+   * so the band [X, X+bw] sits on integers) passes at any width, odd or even;
+   * a 1px stroke on integer path coordinates is genuinely a two-row 50% band
+   * and must keep falling back, because the fast path would not reproduce it.
    */
   _tryStrokeBox(box) {
     // the same off switch as the fill's — see _tryRoundRectFill
@@ -1742,12 +1761,27 @@ class RenderingContext2d {
     const Y0 = y - bw / 2;
     const W = w + bw; // outer band size
     const H = h + bw;
+    // What the route needs is that the *ink* is pixel-aligned: the band's
+    // four outer edges on integers, which is what the four tests below say,
+    // and an integer width so the straight runs are whole rows and columns
+    // of FillRectangles (fractional extents would be truncated on the wire —
+    // and a fractional lineWidth passes the outer-band tests, e.g. x = 0.75
+    // with bw = 1.5, so this clause carries real weight).
+    //
+    // The *path* radius is free. The corner glyph box is cut at
+    // K = ceil(r + bw/2), and from the arc's tangent point out to that cut
+    // the band is already its own straight continuation — bw whole rows —
+    // so a fractional radius rides inside the glyph, which rasterizes on the
+    // device pixel grid, exactly as it does on the polygon route. This is
+    // what a border inset by bw/2 needs: nesting inside a background corner
+    // of radius R means a path radius of R - bw/2, half-integer for every
+    // odd width (issue #217).
     if (
       !Number.isInteger(X0) ||
       !Number.isInteger(Y0) ||
       !Number.isInteger(W) ||
       !Number.isInteger(H) ||
-      !Number.isInteger(r)
+      !Number.isInteger(bw)
     ) {
       return this._shapeMiss("fractional");
     }
@@ -2384,6 +2418,7 @@ class RenderingContext2d {
       weight: parsed.weight,
       style: parsed.style,
       size: parsed.size,
+      variations: this._fontVariations,
     };
     style.font = this.window.app.fonts.match(style.family, style);
     this._lastFontString = val;
@@ -2394,6 +2429,28 @@ class RenderingContext2d {
     return this._lastFontString || DEFAULT_FONT;
   }
 
+  /**
+   * CSS's `font-variation-settings`, for a variable font: `'"wght" 460'`,
+   * or `{ wght: 460 }`. Axes a font does not have are ignored and values are
+   * clamped to their range, so this is safe to set unconditionally.
+   *
+   * The `wght` axis needs none of this — a numeric weight in the `font`
+   * shorthand already drives it (`ctx.font = '460 40px Inter'`). This is for
+   * the rest: `wdth`, `slnt`, `opsz` and whatever a display face invents.
+   *
+   * Order-independent: setting it after `font` re-resolves the face, so the
+   * two can be assigned either way round.
+   */
+  set fontVariationSettings(val) {
+    this._fontVariations = parseVariationSettings(val);
+    // re-resolve against the font already in force, if there is one
+    if (this._textStyle) this.font = this._lastFontString;
+  }
+
+  get fontVariationSettings() {
+    return this._fontVariations ?? null;
+  }
+
   // ------------------------------------------------------------------
   // gradients / images
 

package/lib/text/font.js

@@ -2,6 +2,60 @@ import * as fontkit from 'fontkit';
 
 import { flatten, rasterizePath } from '../rasterize.js';
 
+// Axis coordinates are rounded to this many decimals before anything is
+// instantiated or cached. Every distinct coordinate is a font in its own
+// right — its own rasterized glyphs, its own server-side glyphset — so the
+// precision of the number that reaches here is the precision of the cache,
+// and a slider handing over 459.9999999997 must not mint a face that
+// 460 will never hit again. Two decimals is far finer than any axis is
+// perceptible at, and makes the coordinate that reaches fontkit and the
+// coordinate in the key the same number by construction.
+const AXIS_DECIMALS = 2;
+const round = (v) => Number(v.toFixed(AXIS_DECIMALS));
+
+// Instances kept per base font. Reached only by an app driving an axis
+// continuously — an animation, a drag — where the tail is cold by
+// definition; a design system's handful of weights never approaches it.
+// Server-side glyph pages have their own byte budget (text/glyphs.js), and
+// evicting a Font here does not strand them: the key is derived from the
+// coordinates, so re-instantiating the same point produces the same key and
+// finds the same page.
+const MAX_INSTANCES = 64;
+
+/**
+ * Clamp `settings` into a font's design space: drop axes it does not have,
+ * clamp the rest to their range, round, and drop anything left sitting on
+ * its own default (the base font already *is* the default instance).
+ *
+ * @returns {object|null} the coordinates to instantiate, or null for "this
+ *   font already is that instance"
+ */
+export function normalizeVariations(settings, axes) {
+  if (!settings || !axes) return null;
+  const coords = {};
+  let any = false;
+  for (const tag of Object.keys(settings).sort()) {
+    const axis = axes[tag];
+    if (!axis) continue; // a font that has no such axis is not wrong, just flat
+    const value = Number(settings[tag]);
+    if (!Number.isFinite(value)) continue;
+    const clamped = round(Math.min(axis.max, Math.max(axis.min, value)));
+    if (clamped === round(axis.default)) continue;
+    coords[tag] = clamped;
+    any = true;
+  }
+  return any ? coords : null;
+}
+
+/** Canonical cache key for normalized coordinates: `wdth=87.5,wght=460`. */
+export function variationKey(coords) {
+  if (!coords) return '';
+  return Object.keys(coords)
+    .sort()
+    .map((tag) => `${tag}=${coords[tag]}`)
+    .join(',');
+}
+
 /**
  * A single font face (one entry of a .ttc collection, or a whole .ttf/.otf),
  * parsed with fontkit. Wraps everything the text pipeline needs:
@@ -71,6 +125,94 @@ export default class Font {
     return this.fk.unitsPerEm;
   }
 
+  /**
+   * The variation axes this face offers, keyed by OpenType tag:
+   * `{ wght: { name, min, default, max } }`. `{}` for a static font, so
+   * `Object.keys(font.variationAxes).length` is the "is this variable?"
+   * question and needs no other API.
+   */
+  get variationAxes() {
+    return this.fk.variationAxes ?? {};
+  }
+
+  /**
+   * A static instance of this face at a point in its design space — the
+   * thing a variable font is *for*. `font.variation({ wght: 460 })` is the
+   * `font-variation-settings: "wght" 460` of CSS.
+   *
+   * Instances are ordinary `Font`s from here on: they shape, measure and
+   * rasterize like any face, and because the key is derived from the
+   * coordinates they get their own glyph page and their own server-side
+   * glyphset. That is what keeps the axis honest — leave the key alone and
+   * every instance of one file collides in the glyph cache, so the whole
+   * axis renders as whichever coordinate got there first.
+   *
+   * Nothing is rasterized here. Instantiating is a table-level operation;
+   * glyphs are still rasterized one at a time, on first use, at the size
+   * they are drawn at.
+   *
+   * Settings for axes this font does not have are ignored, values are
+   * clamped to each axis's range, and coordinates that land on their own
+   * default return **this font** rather than a redundant copy of it.
+   *
+   * @param {object} settings axis tag -> value, e.g. `{ wght: 460 }`
+   * @returns {Font} the instance, or `this` when the settings are a no-op
+   */
+  variation(settings) {
+    const coords = normalizeVariations(settings, this.variationAxes);
+    if (!coords) return this;
+    const suffix = variationKey(coords);
+
+    if (!this._variations) this._variations = new Map();
+    const cached = this._variations.get(suffix);
+    if (cached) {
+      // Map iterates in insertion order: re-inserting a hit moves it to the
+      // tail, so the eviction below drops the least recently asked for
+      this._variations.delete(suffix);
+      this._variations.set(suffix, cached);
+      return cached;
+    }
+
+    const instance = new Font(this._instantiate(coords), this.path, this.postscriptName);
+    instance.key = `${this.key}|${suffix}`;
+    /** the face this was cut from, for callers walking back to the axes */
+    instance.variationOf = this;
+    instance.variationCoords = coords;
+
+    this._variations.set(suffix, instance);
+    if (this._variations.size > MAX_INSTANCES) {
+      const oldest = this._variations.keys().next().value;
+      this._variations.delete(oldest);
+    }
+    return instance;
+  }
+
+  /**
+   * fontkit's instancing, with the one failure it has turned into something
+   * that says what to do about it.
+   *
+   * `getVariation` rebuilds the face from the original stream at the
+   * original directory offset. For a WOFF2 that stream is still
+   * Brotli-compressed, so the copy comes back with a directory parsed out of
+   * compressed bytes — no `cmap`, and a `Cannot read properties of undefined
+   * (reading 'tables')` from somewhere deep in shaping, at the first
+   * character drawn rather than here. Checking the instance is well-formed
+   * costs one property read and moves the report to the call that caused it.
+   */
+  _instantiate(coords) {
+    const instance = this.fk.getVariation(coords);
+    if (!instance?.directory?.tables?.cmap) {
+      throw new Error(
+        `ntk: cannot instantiate a variation of ${this.postscriptName || this.key}` +
+          (this.fk.type ? ` (${this.fk.type})` : '') +
+          '. fontkit can only instantiate axes from an uncompressed font — ' +
+          'ship the .ttf/.otf of a variable font rather than its .woff2. ' +
+          'See docs/fonts.md#variable-fonts'
+      );
+    }
+    return instance;
+  }
+
   scale(size) {
     return size / this.fk.unitsPerEm;
   }

package/lib/text/fontmanager.js

@@ -8,6 +8,41 @@ import {
 import { embeddingLevels, normalizedLevels, shapeText } from './shape.js';
 import { TextLayout } from './layout.js';
 
+// Bound on the resolved-match map. See the sweep in `match()`.
+const MAX_MATCHES = 512;
+
+/** Cache-key fragment for a style's `variations`, before any font is known. */
+function variationsKeyOf(variations) {
+  if (!variations) return '';
+  return Object.keys(variations)
+    .sort()
+    .map((tag) => `${tag}=${variations[tag]}`)
+    .join(',');
+}
+
+/**
+ * Put a resolved face at the point in its design space the style asked for.
+ *
+ * The interesting half is `weight`. CSS has said for years that
+ * `font-weight: 460` on a variable font means the `wght` axis at 460, not
+ * "the nearest face"; a face with a `wght` axis therefore takes the
+ * requested weight as a coordinate, and an app that hands ntk a variable
+ * file gets the weight it asked for without knowing an axis exists. An
+ * explicit `variations.wght` wins, because a caller naming the axis
+ * directly is being more specific than one naming a weight.
+ *
+ * Everything here is a no-op for a static face: `variation()` returns the
+ * font unchanged when the settings do not apply, so this costs one property
+ * read on the path every non-variable app is already on.
+ */
+function instantiate(font, weight, variations) {
+  const axes = font.variationAxes;
+  if (!axes || (!axes.wght && !variations)) return font;
+  const settings = { ...variations };
+  if (axes.wght && settings.wght === undefined) settings.wght = weight;
+  return font.variation(settings);
+}
+
 /**
  * Font lookup, loading and caching — the entry point of the text API,
  * available as `app.fonts` (and constructible standalone for headless
@@ -122,9 +157,14 @@ export default class FontManager {
   match(family = 'sans-serif', opts = {}) {
     const weight = numWeight(opts.weight);
     const italic = !!(opts.style && opts.style.includes('italic'));
-    const cacheKey = `${family}|${weight}|${italic}`;
+    const cacheKey = `${family}|${weight}|${italic}|${variationsKeyOf(opts.variations)}`;
     let font = this._matches.get(cacheKey);
-    if (font) return font;
+    if (font) {
+      // insertion order is LRU order; re-inserting a hit moves it to the tail
+      this._matches.delete(cacheKey);
+      this._matches.set(cacheKey, font);
+      return font;
+    }
 
     const families = String(family)
       .split(',')
@@ -145,7 +185,19 @@ export default class FontManager {
       });
       font = this._open(candidates[0]);
     }
+    font = instantiate(font, weight, opts.variations);
     this._matches.set(cacheKey, font);
+    // The key now carries a point in a continuous space rather than one of a
+    // handful of weights, so an app animating an axis walks this map instead
+    // of hitting it. Same sweep as the shaping memo: drop the stale half in
+    // one pass rather than one entry per insert.
+    if (this._matches.size > MAX_MATCHES) {
+      let drop = this._matches.size >> 1;
+      for (const key of this._matches.keys()) {
+        if (drop-- <= 0) break;
+        this._matches.delete(key);
+      }
+    }
     return font;
   }
 
@@ -239,7 +291,15 @@ export default class FontManager {
    */
   _shapeCached(text, style, levelsKey = '0') {
     const font = style.font;
-    const key = `${font ? font.key : style.family}|${style.size}|${style.weight}|${style.style}|${levelsKey}|${text}`;
+    // A resolved `font` already carries its coordinates in its key, so the
+    // variations fragment only earns its keep on the family path — where two
+    // points of one axis would otherwise share a shaped run, and the second
+    // would be drawn with the first's advances.
+    const key = font
+      ? `${font.key}|${style.size}|${style.weight}|${style.style}|${levelsKey}|${text}`
+      : `${style.family}|${style.size}|${style.weight}|${style.style}|${variationsKeyOf(
+          style.variations
+        )}|${levelsKey}|${text}`;
     let shaped = this._shapeCache.get(key);
     if (shaped) {
       // Map iterates in insertion order: re-inserting a hit moves it to the

package/lib/text/layout.js

@@ -66,6 +66,7 @@ export class TextLayout {
         size: s.size ?? style.size ?? 16,
         weight: s.weight ?? style.weight,
         style: s.style ?? style.style,
+        variations: s.variations ?? style.variations,
         features: s.features ?? style.features,
         language: s.language ?? style.language,
         color: s.color ?? style.color ?? null

package/lib/window.js

@@ -41,6 +41,63 @@ const SPLIT_SAVING = 0.75;
  */
 const BACKING_GRANULARITY = 128;
 
+/**
+ * Frame period assumed before anything better is known, in ms.
+ *
+ * The fence clock's rate limit, and the vblank clock's placeholder until the
+ * display has reported its own period (see _sampleRefresh).
+ */
+const DEFAULT_FRAME_INTERVAL = 16;
+
+/**
+ * The range a measured vblank period has to fall in to be believed, in ms.
+ *
+ * Completion timestamps come from the server's clock and its idea of a frame
+ * counter, neither of which is guaranteed to mean what it does on a physical
+ * output — a window with no CRTC behind it gets a synthesized msc, and an idle
+ * gap between two presents inflates the period derived from them. A sample
+ * outside 1000Hz..10Hz is not a refresh rate and is dropped.
+ */
+const MIN_REFRESH_INTERVAL = 1;
+const MAX_REFRESH_INTERVAL = 100;
+
+/**
+ * How many recent completion intervals the refresh estimate is drawn from,
+ * and how far up their sorted order it reads.
+ *
+ * Near the bottom rather than the middle, because what the msc counts is not
+ * the same everywhere. Where it counts vertical blanks a one-blank gap is
+ * exactly one period and every sample agrees; where it counts *presents* —
+ * Xwayland advances it once per frame the compositor takes — a slow frame
+ * reports its own duration as if it were the display's, and only the quick
+ * frames are telling the truth. Not the outright minimum, because a
+ * timer-driven fake vblank (Xvfb) jitters in both directions and a single
+ * short gap should not become the answer. A history, rather than a running
+ * value, is what lets the estimate rise again after a mode change to a slower
+ * rate.
+ */
+const REFRESH_SAMPLES = 16;
+const REFRESH_QUANTILE = 0.25;
+
+/**
+ * How long a frame may stay outstanding before the vblank clock is abandoned
+ * for the fence, in ms.
+ *
+ * Deliberately far above any frame rate: this is a deadlock breaker, not a
+ * pacer, and the rate a window is *legitimately* given can be very low. A
+ * Wayland compositor throttles a window nobody can see — measured at ~1Hz for
+ * an occluded window under Mutter — by simply not sending the frame callback
+ * that completes its present, and that window is right to stop rendering.
+ * Waking it up to run frames at fence rate would burn CPU on pixels no one
+ * sees, so the timeout has to sit above the slowest honest answer.
+ *
+ * A server that never completes anything is a different case and worth
+ * catching quickly, so the first present a window ever sends is given the
+ * shorter deadline — nothing has proved it will be answered yet.
+ */
+const STALL_TIMEOUT = 2000;
+const STALL_TIMEOUT_FIRST = 250;
+
 function rectArea(r) {
   return Math.max(0, r.w) * Math.max(0, r.h);
 }
@@ -359,6 +416,10 @@ export default class Window extends Drawable {
     // (see docs/window.md "Frames, coalescing and slow connections")
     this._coalesce = args.coalesceEvents !== false;
     this._frameSyncEnabled = args.frameSync !== false;
+    // which signal ends a frame (see _clockOnPresent): 'auto' takes the
+    // display's own vblank where the Present path can supply it and the fence
+    // everywhere else, 'fence' pins the round-trip clock
+    this._frameClockPref = args.frameClock ?? 'auto';
     // _NET_WM_SYNC_REQUEST (see enableSyncRequest): the counter the window
     // manager watches, the value it last asked for, and the watchdog that
     // guarantees an answer even when nothing repaints
@@ -373,13 +434,34 @@ export default class Window extends Drawable {
     this._fixesExt = null;
     this._updateRegion = 0;
     this._presentSerial = 0;
-    this.frameInterval = args.frameInterval ?? 16;
+    this._presentEid = 0;
+    // The vblank clock (see _onPresentComplete): the period learnt from
+    // completion events, the samples it is drawn from, and the latch the
+    // watchdog sets when completions stop arriving.
+    this.refreshInterval = null;
+    this.droppedFrames = 0;
+    this._refreshSamples = [];
+    this._lastComplete = null;
+    this._clockStalled = false;
+    // `frameInterval` is a plain number, but whether the caller set it is what
+    // decides its meaning under the vblank clock — an explicit value caps the
+    // frame rate, an unasked-for default must not (see _armTimer). Assigning
+    // the property later is the caller setting it, hence the accessor.
+    //
+    // The default is the display's own period where the connection has found
+    // it out, and DEFAULT_FRAME_INTERVAL until it has: a window built before
+    // that probe answers adopts the result when it lands.
+    this._frameInterval = args.frameInterval ?? app.frameInterval ?? DEFAULT_FRAME_INTERVAL;
+    this._frameIntervalExplicit = args.frameInterval !== undefined;
     this.frameLatency = null;
     this._frame = {
       pending: new Map(), // coalescible event name -> merged event
       rafCbs: [],
       rafId: 0,
       inFlight: false, // fence round-trip awaiting the server's reply
+      presentInFlight: false, // present awaiting the display's CompleteNotify
+      presentAt: 0, // when that present was sent, for frameLatency
+      stallTimer: null,
       timer: null,
       scheduled: false,
       needsRedraw: false,
@@ -511,14 +593,30 @@ export default class Window extends Drawable {
       // the earliest. `await wnd.enableSyncRequest()` when that is too close.
       this.enableSyncRequest().catch((err) => this.app.options.onXError?.(err));
     }
+    // Presenting is what a double-buffered window does unless it says
+    // otherwise, so the decision is deferred to the point one gets a backing
+    // store (see _enableBackingStore): a window drawing through 'opengl' or
+    // 'x11' has no pixmap to present and would only be paying for an update
+    // region and an event selection it never uses. `present: true` is still
+    // honoured eagerly, for a caller who wants it up before the first paint.
+    this._presentOptOut = args.present === false;
     if (args.present && !args.id) {
       // fire and forget: until the extensions answer, blits use CopyArea,
       // which is what they would have done anyway
-      this.enablePresent().catch((err) => this.app.options.onXError?.(err));
+      this.enablePresent().catch((err) => this.app.options?.onXError?.(err));
     }
 
     X.event_consumers[this.id] = this;
     this.on('event', (ev) => {
+      // Present speaks in X Generic Events, which carry an extension opcode
+      // and a sub-type where a core event carries its code — the name table
+      // below cannot see them, and they are not events user code asked for
+      if (ev.type === 35) {
+        if (this._presentExt && ev.extension === this._presentExt.majorOpcode) {
+          this._handlePresentEvent(ev);
+        }
+        return;
+      }
       const ntkev = ev; // todo: clone
       ntkev.window = this;
       ntkev.target = this;
@@ -640,7 +738,7 @@ export default class Window extends Drawable {
     this.on('destroy', () => {
       this._destroyed = true;
       this._forget();
-      this._teardownFrame();
+      this._teardownFrame(false); // the server has already taken the window
       // the server frees window-backed pictures with the window — let
       // contexts drop their wrappers without issuing FreePicture
       this.emit('_destroyed');
@@ -676,6 +774,12 @@ export default class Window extends Drawable {
     this._dirty = false;
     this._backingValid = false;
     this._presentScheduled = false;
+    // Now there is a pixmap to present. Inert where the extensions are
+    // missing, so this costs a window on such a server two extension queries
+    // that node-x11 answers from its cache after the first.
+    if (!this._presentOptOut && !this._foreign) {
+      this.enablePresent().catch((err) => this.app.options?.onXError?.(err));
+    }
 
     this._presentGc = this.X.AllocID();
     this.X.CreateGC(this._presentGc, this.id, { graphicsExposures: 0 });
@@ -897,39 +1001,120 @@ export default class Window extends Drawable {
 
   /*
    * Frame clock. Noisy events (see events_map coalesce), synthetic redraws
-   * and requestAnimationFrame callbacks are delivered in "frames", paced by
-   * two independent gates:
-   *
-   *  - a fence: a cheap request with a reply (GetInputFocus) sent after each
-   *    frame; X processes requests in order, so its reply confirms the
-   *    server consumed everything the frame drew. At most one fence is in
-   *    flight — on a slow connection frames degrade to one per round-trip
-   *    instead of queueing a trail of stale updates.
-   *  - a timer: at most one paced frame per `frameInterval` ms, so a fast
-   *    local server doesn't get redraws at input-device rate.
+   * and requestAnimationFrame callbacks are delivered in "frames". What ends
+   * a frame — and so what paces the next one — is one of two signals:
+   *
+   *  - the display, on a window presenting through the Present extension: the
+   *    CompleteNotify for the frame's PresentPixmap, which the server sends
+   *    when it has executed the copy at a vertical blank. Frames then run at
+   *    the output's own rate, phase-locked to it, whatever that rate is.
+   *  - a fence, everywhere else: a cheap request with a reply
+   *    (GetInputFocus) sent after each frame; X processes requests in order,
+   *    so its reply confirms the server consumed everything the frame drew.
+   *
+   * Either way at most one is outstanding, which is what bounds the work in
+   * flight: on a slow connection frames degrade to one per round-trip instead
+   * of queueing a trail of stale updates.
+   *
+   * A timer backs both up. Under the fence it is the rate limit — at most one
+   * frame per `frameInterval` ms, so a fast local server isn't asked to redraw
+   * at input-device rate. Under the vblank clock the display is the rate
+   * limit, and the timer only covers frames that drew nothing: those produce
+   * no present, so no completion is coming and something else has to run the
+   * next frame (`refreshInterval` is the period there, so a compute-only
+   * animation loop still runs at display rate).
    *
    * Discrete events (mousedown, keydown, ...) bypass the timer for latency:
    * the first blit after a quiet moment goes out with the handler's own
-   * requests. Their blits are still bounded, by the fence and by a minimum
-   * inter-blit interval (also `frameInterval`) — see _present(). Without that
-   * interval a stream of discrete events blits at round-trip rate, which on a
-   * local server is several hundred per second, and under a compositor every
-   * blit is a recomposite.
+   * requests. Their blits are still bounded, by whichever clock is running and
+   * by a minimum inter-blit interval (`frameInterval` again) — see _present().
+   * Without that interval a stream of discrete events blits at round-trip
+   * rate, which on a local server is several hundred per second, and under a
+   * compositor every blit is a recomposite. The vblank clock has no need of
+   * it: a present outstanding already means the display has not caught up.
    */
   _scheduleFrame() {
     const f = this._frame;
-    if (f.scheduled || f.inFlight || f.timer) return;
+    if (f.scheduled || f.inFlight || f.presentInFlight || f.timer) return;
     f.scheduled = true;
     setImmediate(() => {
       f.scheduled = false;
       // gates may have been armed after this got scheduled (work queued
       // from inside a running frame, e.g. a rAF loop re-registering) —
-      // the fence reply / timer expiry will reschedule then
-      if (f.inFlight || f.timer) return;
+      // the completion / fence reply / timer expiry will reschedule then
+      if (f.inFlight || f.presentInFlight || f.timer) return;
       this._runFrame();
     });
   }
 
+  /**
+   * Minimum ms between paced frames, and between blits.
+   *
+   * Under the vblank clock an *explicit* value is a cap on top of the
+   * display's rate — `frameInterval: 33` renders at 30fps on any output,
+   * which is a real ask on battery — while the default must not cap anything,
+   * or a 165Hz display would be held to the 62.5fps that 16ms implies.
+   * Assigning the property counts as explicit, which is why this is an
+   * accessor: `wnd.frameInterval = 33` has to mean the same as passing it.
+   */
+  get frameInterval() {
+    return this._frameInterval;
+  }
+
+  set frameInterval(ms) {
+    this._frameInterval = ms;
+    this._frameIntervalExplicit = true;
+  }
+
+  /**
+   * Take the connection's measured default, if this window is still on the
+   * guess. Called when the RandR probe answers, which is normally a few
+   * round trips after the first window was built — see App#_probeRefreshRate.
+   */
+  _adoptDefaultFrameInterval(ms) {
+    if (this._frameIntervalExplicit || this._destroyed) return;
+    this._frameInterval = ms;
+  }
+
+  /**
+   * Which clock is ending this window's frames right now: 'present' when the
+   * display is, 'fence' when the server round-trip is. Assignable with
+   * 'auto' (prefer the display) or 'fence' (never use it).
+   */
+  get frameClock() {
+    return this._clockOnPresent() ? 'present' : 'fence';
+  }
+
+  set frameClock(mode) {
+    this._frameClockPref = mode === 'present' ? 'auto' : mode;
+    if (this._frameClockPref !== 'fence') this._selectPresentInput();
+  }
+
+  /**
+   * Is the display ending frames on this window, rather than the socket?
+   *
+   * Needs the Present path up (there is no completion event without it) and
+   * the frame sync the caller may have turned off — `frameSync: false` asks
+   * for pacing that never waits on the server, and a completion is the
+   * strongest wait there is. `_clockStalled` is the watchdog's latch: a
+   * completion that never came drops the window back to the fence until one
+   * does, so a clock that stops cannot stop the window with it.
+   *
+   * `_presentFlipped` is the one-way door — a server that has flipped a copy
+   * present is off this path for good, and its blits no longer produce the
+   * completions the clock is made of.
+   */
+  _clockOnPresent() {
+    return (
+      this._frameClockPref !== 'fence' &&
+      this._frameSyncEnabled &&
+      !this._clockStalled &&
+      !this._presentFlipped &&
+      !!this._presentExt &&
+      !!this._presentEid
+    );
+  }
+
   _runFrame() {
     const f = this._frame;
     if (
@@ -966,7 +1151,10 @@ export default class Window extends Drawable {
     // covers a window with no backing store, and a resize that changed
     // nothing: _presentNow did not run, but the frame is still "handled"
     this._ackSyncRequest();
-    this._armFence();
+    // A frame that presented is already clocked — its completion ends it. One
+    // that drew nothing has to fall back to the timer, or nothing would ever
+    // run the next frame.
+    if (!this._clockOnPresent()) this._armFence();
     this._armTimer();
   }
 
@@ -1063,29 +1251,209 @@ export default class Window extends Drawable {
       this.X.GetInputFocus(() => {
         f.inFlight = false;
         this.frameLatency = performance.now() - start;
-        if (this._presentPending) {
-          // a blit deferred while the fence was in flight: show it as soon as
-          // the minimum inter-blit interval allows (immediately when the last
-          // blit is already older than that, which is the common case)
-          this._present();
-        }
-        if ((f.pending.size || f.rafCbs.length || f.needsRedraw) && !f.timer) this._scheduleFrame();
+        this._frameEnded();
       });
     });
   }
 
+  /**
+   * Present's events, which are the ones the core event table cannot name:
+   * they arrive as X Generic Events (type 35), carrying an extension opcode
+   * and a sub-type instead of an event code.
+   */
+  _handlePresentEvent(ev) {
+    const P = this._presentExt;
+    if (!P || ev.evtype !== P.events.CompleteNotify) return;
+    if (ev.kind !== P.CompleteKind.Pixmap) return; // not a frame of ours
+    if (ev.mode === P.CompleteMode.Flip) {
+      // The server took the pixmap for scanout instead of copying it, and
+      // keeps it until some later present — but ntk has one grow-only backing
+      // pixmap and is about to draw into it, which would now paint the screen
+      // directly. Option.Copy is passed on every present precisely so this
+      // cannot happen (presentproto: "'pixmap' will be idle ... as soon as the
+      // operation occurs"), so a server doing it anyway is one whose Present
+      // path we cannot use at all.
+      this._presentFlipped = true;
+      this.app.options.onXError?.(
+        new Error(
+          'ntk: the X server flipped a present sent with Option.Copy, which leaves it ' +
+            "owning the window's backing pixmap — falling back to CopyArea blits"
+        )
+      );
+      this._stallClock();
+      return;
+    }
+    this._onPresentComplete(ev);
+  }
+
+  /**
+   * A frame reached the display: the server executed the copy, at a vblank.
+   *
+   * This is `_armFence`'s reply callback with a better trigger behind it. The
+   * fence proves the server *read* the frame's requests; this proves it *ran*
+   * them, on the output, which is both a stronger flow-control signal and the
+   * moment the backing pixmap is ours to draw into again.
+   */
+  _onPresentComplete(ev) {
+    const f = this._frame;
+    const now = performance.now();
+    this._clearStallWatchdog();
+    // completions are arriving again, whatever the watchdog concluded before
+    this._clockStalled = false;
+    if (!f.presentInFlight) return; // a completion we are not clocking on
+    f.presentInFlight = false;
+    this.frameLatency = now - f.presentAt;
+    this._sampleRefresh(ev, now);
+    this._frameEnded();
+  }
+
+  /**
+   * What both clocks do when a frame ends: send the blit that was held back
+   * behind it, then run the next frame if anything is waiting for one.
+   */
+  _frameEnded() {
+    const f = this._frame;
+    if (this._presentPending) {
+      // a blit deferred while the frame was outstanding: show it as soon as
+      // the pacing allows, which under the vblank clock is now
+      this._present();
+    }
+    if ((f.pending.size || f.rafCbs.length || f.needsRedraw) && !f.timer) this._scheduleFrame();
+  }
+
+  /**
+   * Learn the display's refresh period from the frame that just landed.
+   *
+   * Two completions give it without asking anyone: `ust` is when the
+   * presentation happened (microseconds, on the server's clock) and `msc`
+   * counts the frames between them, so their ratio is one vblank. Nothing is
+   * configured, nothing is queried, and it follows the window to another
+   * monitor or through a mode change on its own — where a RandR lookup would
+   * need change-tracking to keep up.
+   *
+   * Only differences are read from the server clock, never an absolute time,
+   * and a sample is believed only if it lands in the range a refresh rate can
+   * be in — which is also what keeps a window the compositor has throttled to
+   * a frame a second from being mistaken for a 1Hz display.
+   */
+  _sampleRefresh(ev, now) {
+    const prev = this._lastComplete;
+    this._lastComplete = { msc: ev.msc, ust: ev.ust, at: now };
+    if (!prev || !(ev.msc > prev.msc)) return;
+    const frames = ev.msc - prev.msc;
+    // Frames the display went through without one of ours. Counted from the
+    // msc, which is the only place the information exists: where the counter
+    // tracks presents rather than vblanks the gap is always 1 and a miss is
+    // simply not observable, and reporting nothing beats inferring it from
+    // elapsed time on a server whose timing is synthetic to begin with.
+    //
+    // Only across a gap short enough to have been a frame at all. A window
+    // that sat idle between two clicks also let the counter run, and that is
+    // not a dropped frame; past a tenth of a second the two are anyway
+    // indistinguishable, and under-reporting is the right way for a
+    // diagnostic to be wrong.
+    if (now - prev.at <= MAX_REFRESH_INTERVAL) this.droppedFrames += frames - 1;
+    // Only a single-frame gap measures a frame's length. A longer one spans a
+    // miss, and dividing it out assumes the msc advanced for the same reason
+    // in each — true of a hardware counter, false of one driven off a timer,
+    // where it makes a late frame look like a *faster* display.
+    if (frames !== 1) return;
+    // ust is the server's clock and local receipt is ours; they measure the
+    // same interval, so the local one stands in when ust is not usable (a
+    // synthesized msc can carry a ust that does not move with it)
+    const byUst = (ev.ust - prev.ust) / 1000;
+    const sample = byUst >= MIN_REFRESH_INTERVAL ? byUst : now - prev.at;
+    if (!(sample >= MIN_REFRESH_INTERVAL && sample <= MAX_REFRESH_INTERVAL)) return;
+    const samples = this._refreshSamples;
+    samples.push(sample);
+    if (samples.length > REFRESH_SAMPLES) samples.shift();
+    const sorted = [...samples].sort((a, b) => a - b);
+    this.refreshInterval = sorted[Math.floor(REFRESH_QUANTILE * (sorted.length - 1))];
+  }
+
+  /**
+   * Guarantee that a frame ends even if its completion does not arrive.
+   *
+   * A fence is a request with a reply and the server always sends one. A
+   * completion is an event about work the server may never do: an unmapped
+   * window, a compositor changing its mind about redirection, or simply a
+   * server whose Present is a stub. `_presentPending` has exactly one wakeup,
+   * so a completion that never comes would be a window that never updates
+   * again — a permanently stale window, which is the trap #195 hit.
+   *
+   * See STALL_TIMEOUT for why the deadline is measured in seconds rather than
+   * in frames: a slow answer is usually the display being honest about how
+   * often this window is worth drawing.
+   */
+  _armStallWatchdog() {
+    const f = this._frame;
+    if (f.stallTimer) return;
+    const timeout = this._lastComplete ? STALL_TIMEOUT : STALL_TIMEOUT_FIRST;
+    f.stallTimer = setTimeout(() => {
+      f.stallTimer = null;
+      if (f.presentInFlight) this._stallClock();
+    }, timeout);
+    if (typeof f.stallTimer.unref === 'function') f.stallTimer.unref();
+  }
+
+  _clearStallWatchdog() {
+    const f = this._frame;
+    if (!f.stallTimer) return;
+    clearTimeout(f.stallTimer);
+    f.stallTimer = null;
+  }
+
+  /**
+   * Give up on the display as a clock, for now. The fence takes over, and the
+   * next completion to arrive hands it back (see _onPresentComplete) — a
+   * window that is merely unmapped for a while must not be left on the slower
+   * clock forever.
+   */
+  _stallClock() {
+    const f = this._frame;
+    this._clockStalled = true;
+    f.presentInFlight = false;
+    this._clearStallWatchdog();
+    // nothing else needs re-arming: an idle window wants no clock, and the
+    // frame _frameEnded schedules will arm the fence on its way out
+    this._frameEnded();
+  }
+
+  /**
+   * The timer gate, whose period depends on what it is standing in for.
+   *
+   * Under the fence it is the rate limit and `frameInterval` is the period.
+   * Under the vblank clock it is the fallback for a frame that presented
+   * nothing — there is no completion coming for a frame that drew nothing —
+   * so the period is the display's, and a frame that *did* present arms no
+   * timer at all: the completion is closer and more accurate than any timer,
+   * and arming one would only cap the rate the display just set. An explicit
+   * `frameInterval` is honoured in both, since a cap the caller asked for
+   * applies whatever ends the frame.
+   */
   _armTimer() {
-    if (!(this.frameInterval > 0)) return;
     const f = this._frame;
     if (f.timer) return;
+    let period = this.frameInterval;
+    if (this._clockOnPresent() && !this._frameIntervalExplicit) {
+      if (f.presentInFlight) return;
+      period = this.refreshInterval ?? DEFAULT_FRAME_INTERVAL;
+    }
+    if (!(period > 0)) return;
     f.timer = setTimeout(() => {
       f.timer = null;
       if (f.pending.size || f.rafCbs.length || f.needsRedraw) this._scheduleFrame();
-    }, this.frameInterval);
+    }, period);
     if (typeof f.timer.unref === 'function') f.timer.unref();
   }
 
-  _teardownFrame() {
+  /**
+   * @param {boolean} [windowAlive] false when the server has already destroyed
+   *   the window (a DestroyNotify), which takes its Present event context with
+   *   it — deleting one explicitly then is a request against a window id that
+   *   no longer exists, i.e. a BadWindow for the app's error hook to explain.
+   */
+  _teardownFrame(windowAlive = true) {
     const f = this._frame;
     if (f.timer) {
       clearTimeout(f.timer);
@@ -1095,6 +1463,18 @@ export default class Window extends Drawable {
       clearTimeout(f.presentTimer);
       f.presentTimer = null;
     }
+    this._clearStallWatchdog();
+    if (this._presentEid) {
+      const eid = this._presentEid;
+      const P = this._presentExt;
+      this._presentEid = 0;
+      f.presentInFlight = false;
+      safeRelease(this.X, () => {
+        // an empty mask deletes the event context (presentproto)
+        if (windowAlive && P) P.SelectInput(eid, this.id, P.EventMask.NoEvent);
+        this.X.ReleaseID(eid);
+      });
+    }
     if (this._syncWatchdog) {
       clearTimeout(this._syncWatchdog);
       this._syncWatchdog = null;
@@ -1129,9 +1509,10 @@ export default class Window extends Drawable {
 
   /**
    * DOM-style requestAnimationFrame: `cb(now)` runs on this window's next
-   * paced frame — at most once per `frameInterval` ms and with at most one
-   * frame's requests unacknowledged by the server, so animation loops adapt
-   * to connection latency instead of flooding a slow link.
+   * paced frame — one per vertical blank where the display is the clock (see
+   * _clockOnPresent), otherwise at most once per `frameInterval` ms — and
+   * always with at most one frame outstanding, so animation loops adapt to
+   * the output's rate and to connection latency instead of flooding either.
    * Returns an id for cancelAnimationFrame().
    */
   requestAnimationFrame(cb) {
@@ -1150,8 +1531,9 @@ export default class Window extends Drawable {
 
   /**
    * Whether a blit this window already owes is still waiting to go out —
-   * because the fence for the last frame is unanswered, or because a present
-   * is deferred behind the minimum inter-blit interval.
+   * because the last frame is unanswered (its fence unreplied, or its present
+   * not yet on the display), or because a present is deferred behind the
+   * minimum inter-blit interval.
    *
    * The one bit of frame-clock state worth publishing, because it is the
    * difference between the two ways a toolkit can answer a discrete input.
@@ -1173,24 +1555,29 @@ export default class Window extends Drawable {
    * "draw it now" to every notch — the precise work this gate exists to skip.
    *
    * `false` whenever nothing gates blits at all: `frameSync: false` sends no
-   * fence and `frameInterval: 0` keeps no interval, so a caller who asked for
-   * both gets the unpaced behaviour those options ask for.
+   * fence and takes the vblank clock with it (a completion is a wait on the
+   * server too), and `frameInterval: 0` keeps no interval, so a caller who
+   * asked for both gets the unpaced behaviour those options ask for.
    */
   frameInFlight() {
-    return this._frame.inFlight || this._presentPending;
+    return this._frame.inFlight || this._frame.presentInFlight || this._presentPending;
   }
 
   _present() {
     if (!this._backing) return;
+    const f = this._frame;
     const wait = this._presentWait();
-    if (this._frame.inFlight || wait > 0) {
-      // the server hasn't confirmed the previous frame yet, or the last blit
-      // was too recent — defer, and leave a wakeup behind
+    if (f.inFlight || f.presentInFlight || wait > 0) {
+      // the server hasn't confirmed the previous frame yet, the display hasn't
+      // shown it, or the last blit was too recent — defer, leaving a wakeup
       this._deferPresent(wait);
       return;
     }
     this._presentNow();
-    this._armFence();
+    // the fence is what ends this blit's frame unless the display is doing
+    // it — which is decided by _presentNow, since a blit that fell back to
+    // CopyArea gets no completion however the clock is configured
+    if (!f.presentInFlight) this._armFence();
   }
 
   /**
@@ -1199,8 +1586,16 @@ export default class Window extends Drawable {
    * The gate is `frameInterval`, the same knob that paces frames, so
    * `frameInterval: 0` keeps the old fence-only behaviour — a caller who asked
    * for no timer gate gets none here either.
+   *
+   * The vblank clock needs no such gate and must not inherit the default one:
+   * an outstanding present already means the display has not caught up, and
+   * that is a truer statement of the same thing than any interval. Holding a
+   * click's repaint for a 16ms default on a 165Hz output is exactly the
+   * latency this gate was careful not to add. An explicit interval still
+   * applies — a cap the caller asked for is a cap.
    */
   _presentWait() {
+    if (this._clockOnPresent() && !this._frameIntervalExplicit) return 0;
     const min = this.frameInterval;
     if (!(min > 0)) return 0;
     const since = performance.now() - this._frame.lastPresentAt;
@@ -1211,16 +1606,17 @@ export default class Window extends Drawable {
    * Hold a blit back, and guarantee it still happens.
    *
    * This is the only place `_presentPending` is set, because every deferral has
-   * to leave a wakeup behind: the fence reply when the fence is what we are
-   * waiting on, this timer when the interval is. Nothing else reschedules a
-   * present — `_scheduleFrame()` bails while a frame timer is armed, and
-   * neither reschedule condition (in `_armFence`'s reply or `_armTimer`'s
-   * callback) looks at the present. Without the timer the last blit of a burst
-   * would simply never go out, leaving stale pixels on screen.
+   * to leave a wakeup behind: the end of the frame we are waiting on (its
+   * fence reply, or its completion), this timer when the interval is what we
+   * are waiting on. Nothing else reschedules a present — `_scheduleFrame()`
+   * bails while a frame timer is armed, and no reschedule condition
+   * (`_frameEnded`, `_armTimer`'s callback) looks at the present. Without the
+   * timer the last blit of a burst would simply never go out, leaving stale
+   * pixels on screen.
    */
   _deferPresent(wait) {
     this._presentPending = true;
-    if (wait <= 0) return; // waiting on the fence: its reply blits this
+    if (wait <= 0) return; // waiting on the frame: its end blits this
     const f = this._frame;
     if (f.presentTimer) return; // already armed
     f.presentTimer = setTimeout(() => {
@@ -1228,9 +1624,9 @@ export default class Window extends Drawable {
       if (!this._presentPending && !this._dirty) return; // someone blitted it
       const again = this._presentWait();
       if (again > 0) return this._deferPresent(again); // a paced frame re-stamped
-      if (f.inFlight) return; // the fence ack is closer; it will blit
+      if (f.inFlight || f.presentInFlight) return; // the frame's end is closer
       this._presentNow();
-      this._armFence();
+      if (!f.presentInFlight) this._armFence();
     }, wait);
     if (typeof f.presentTimer.unref === 'function') f.presentTimer.unref();
   }
@@ -1263,17 +1659,49 @@ export default class Window extends Drawable {
    */
   enablePresent() {
     if (this._presentExt || this._destroyed) return Promise.resolve(this);
+    // Memoized because `createWindow({ present: true })` starts this and
+    // `await wnd.enablePresent()` is the documented way to find out whether it
+    // took — doing both is the normal thing to write, and two runs in flight
+    // at once would each allocate an update region, orphaning one on the
+    // server for the life of the window.
+    if (this._presentPromise) return this._presentPromise;
     const X = this.X;
     const need = (name) =>
       new Promise((resolve) => X.require(name, (err, ext) => resolve(err ? null : ext)));
-    return Promise.all([need('present'), need('fixes')]).then(([present, fixes]) => {
+    this._presentPromise = Promise.all([need('present'), need('fixes')]).then(([present, fixes]) => {
       if (!present || !fixes || this._destroyed) return this; // stay on CopyArea
       this._updateRegion = X.AllocID();
       safeRelease(X, () => fixes.CreateRegion(this._updateRegion, []));
       this._presentExt = present;
       this._fixesExt = fixes;
+      this._selectPresentInput();
       return this;
     });
+    return this._presentPromise;
+  }
+
+  /**
+   * Ask for the completion events the vblank clock runs on.
+   *
+   * CompleteNotify only; IdleNotify would say the same thing twice, since
+   * every present ntk sends carries Option.Copy and the spec makes such a
+   * pixmap idle "as soon as the operation occurs" — the moment the completion
+   * reports. Nothing is selected for a window pinned to the fence, so a
+   * caller who opted out is not sent events it will not read.
+   */
+  _selectPresentInput() {
+    const P = this._presentExt;
+    if (!P || this._presentEid || this._destroyed) return;
+    if (this._frameClockPref === 'fence' || !this._frameSyncEnabled) return;
+    const eid = this.X.AllocID();
+    // the id is only recorded once the request is really on its way: the
+    // clock's whole contract is that a completion will arrive, and a
+    // selection that never left (a connection closing under us) promises
+    // nothing. Failing this way leaves the window on the fence, which works.
+    safeRelease(this.X, () => {
+      P.SelectInput(eid, this.id, P.EventMask.CompleteNotify);
+      this._presentEid = eid;
+    });
   }
 
   /**
@@ -1284,6 +1712,7 @@ export default class Window extends Drawable {
   _presentWithExtension(rects) {
     const P = this._presentExt;
     if (!P || !this._fixesExt || !this._updateRegion) return false;
+    if (this._presentFlipped) return false; // see _handlePresentEvent
     safeRelease(this.X, () => {
       this._fixesExt.SetRegion(
         this._updateRegion,
@@ -1329,10 +1758,20 @@ export default class Window extends Drawable {
     // Stamped here rather than at the call sites so it is a true inter-blit
     // interval across all three of them, and only when pixels really move — a
     // present that copies nothing must not push the next one out.
-    this._frame.lastPresentAt = performance.now();
+    const f = this._frame;
+    f.lastPresentAt = performance.now();
     // Present sends the exact rectangles in one request, so the bounding-box
     // collapse — which trades pixels for fewer requests — has nothing to buy
-    if (!this._presentWithExtension(clamped)) {
+    if (this._presentWithExtension(clamped)) {
+      // This frame is now the display's to end. Only a present through the
+      // extension can be: a CopyArea reports nothing back, so a window that
+      // fell back to it must keep the fence even with the clock configured.
+      if (this._clockOnPresent()) {
+        f.presentInFlight = true;
+        f.presentAt = f.lastPresentAt;
+        this._armStallWatchdog();
+      }
+    } else {
       const rects = this._blitList(clamped);
       // a paced frame can fire after the connection started closing
       safeRelease(this.X, () => {
@@ -1463,8 +1902,9 @@ export default class Window extends Drawable {
 
   /**
    * Intern several atoms and hand them to `cb` as an object keyed by name.
-   * node-x11 caches interned atoms per connection, so a repeated call
-   * costs no round trip. Same deferred-chain hazards as setTitle: by the
+   * Interned atoms are cached per connection — which is true because App
+   * makes it true, see `_isolateAtoms` — so a repeated call costs no round
+   * trip. Same deferred-chain hazards as setTitle: by the
    * time the replies land the window may be gone, so callers re-check
    * `this._destroyed`.
    */
@@ -2932,8 +3372,9 @@ export default class Window extends Drawable {
 
   _emitCloseRequest(ev) {
     if (ev.format !== 32 || !this.listenerCount('close')) return;
-    // node-x11 caches interned atoms per connection, so these are the ids
-    // the 'close' listener's addProtocol already interned
+    // interned atoms are cached per connection (App#_isolateAtoms), so these
+    // are the ids this window's own addProtocol interned — an id another
+    // connection happened to intern would not be one this server still knows
     const X = this.X;
     if (!X.atoms.WM_PROTOCOLS || ev.message_type !== X.atoms.WM_PROTOCOLS) return;
     if (!X.atoms.WM_DELETE_WINDOW || ev.data?.[0] !== X.atoms.WM_DELETE_WINDOW) return;

package/package.json

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