ntk 6.6.1 → 7.0.0

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, () => {