react-x11 2.14.0 → 2.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/glnodes.js

@@ -272,9 +272,18 @@ export class GlAreaNode extends Node {
     // (`EventManager._surfaceAt`).
     this._joinSurfaces();
     this.gl = wnd.getContext('opengl', config);
-    // a buffer freed by the display is a frame that can be drawn again
+    // A buffer freed by the display is a frame that can be drawn again — for
+    // a frame that was waiting for one. The Cocoa surface and the CGL
+    // context reopen their gate one display period after *every* swap, not
+    // only after a refused one, and a request per reopening turned
+    // frameLoop 'demand' into a loop at display rate: a still scene drew
+    // every frame, forever.
     if (typeof this.gl?.onFrameAvailable !== 'undefined') {
-      this.gl.onFrameAvailable = () => this.requestFrame();
+      this.gl.onFrameAvailable = () => {
+        if (!this._frameRefused) return;
+        this._frameRefused = false;
+        this.requestFrame();
+      };
     }
     // The context is only usable once MakeCurrent has answered, and that is
     // where a server refusing indirect GLX says so (ntk gives the rejection
@@ -384,7 +393,10 @@ export class GlAreaNode extends Node {
     // On the direct backend every buffer may still be held by the display,
     // and drawing into one before it comes back would paint what is on
     // screen. `onFrameAvailable` asks for this frame again when one frees.
-    if (direct && gl.canRender && !gl.canRender()) return false;
+    if (direct && gl.canRender && !gl.canRender()) {
+      this._frameRefused = true;
+      return false;
+    }
     // binds this surface — the GPU context is shared between every <glarea>
     // on the connection — and picks up a resize
     gl.makeCurrent?.();

package/src/ntk.js

@@ -37,13 +37,22 @@ export { default } from 'ntk';
  * ntk's offscreen `Surface`, on whichever backend `app` is.
  *
  * An app that makes its own surfaces answers `createSurface(options)` —
- * the Cocoa app does, over a CG bitmap (src/cocoa/surface.js) — and an ntk
+ * the Cocoa app does, over a CG bitmap (src/cocoa/surface.js), the Wayland
+ * app over a GL render target (src/wayland/surface.js) — and an ntk
  * connection has no such method and gets ntk's pixmap. The result is
  * whichever implementation answered, not an instance of this class: the
  * contract is the shape — `width`/`height`, `getContext('2d')`, `render`,
  * `clear`, `copyWithin`, `destroy`, and `ctx.drawImage(surface, …)` —
  * (docs/extending.md "Scrolling the pixels, not just the offset"), and
  * nothing needs `instanceof`.
+ *
+ * Part of that shape is that a context may be **held**: ntk tells a caller
+ * doing many draws to take `getContext('2d')` once rather than one per
+ * frame, and that holds on every backend here, including the ones where a
+ * surface is a GPU target sharing a device with the window (#566). Draws
+ * through a held context land in the surface whenever they are made, and
+ * leave nothing for the caller to restore; `render(fn)` is the scoped form,
+ * for a caller that wants a frame's clean transform and clip.
  */
 export class Surface {
   constructor(app, options) {

package/src/types/system.d.ts

@@ -100,7 +100,8 @@ export function useScale(): number;
 export interface WindowState {
   /** This window has the keyboard. */
   readonly focused: boolean;
-  /** **The one to branch on**: not minimized, and not fully covered. */
+  /** **The one to branch on**: not minimized, not fully covered, and still
+   *  being given frames to draw. */
   readonly visible: boolean;
   /**
    * Fully covered by other windows — **always false when a compositing
@@ -109,6 +110,18 @@ export interface WindowState {
    * entirely visible. Prefer `visible`.
    */
   readonly obscured: boolean;
+  /**
+   * The display is still scheduling frames for this window.
+   *
+   * False on the **Wayland** backend once the compositor has stopped sending
+   * frame callbacks — a surface it is not showing gets none, so nothing the
+   * app draws reaches the screen until it starts again. It is how that
+   * backend answers the question `obscured` answers on a bare X server, it
+   * folds into `visible` the same way, and it takes a couple of seconds of
+   * silence to be sure. Always true where the backend has no such signal:
+   * X11, Cocoa, and the headless mock.
+   */
+  readonly presenting: boolean;
   /** `_NET_WM_STATE_HIDDEN`: iconified, or shaded away. */
   readonly minimized: boolean;
   /** Both axes. One axis alone shows up in `states`. */

package/src/wayland/app.js

@@ -26,6 +26,7 @@
 import { EventEmitter } from 'node:events';
 import { createRequire } from 'node:module';
 import { WaylandConnection } from './connection.js';
+import { releaseDevice } from './device.js';
 import { WaylandSeat } from './seat.js';
 import { WaylandBackendWindow } from './backendwindow.js';
 import { WaylandSurface } from './surface.js';
@@ -107,6 +108,8 @@ export class WaylandApp extends EventEmitter {
     this.outputs = null;
     /** xdg-decoration, layer-shell, shm: null where the compositor has none */
     this.decorationManager = null;
+    /** the older KDE decoration protocol; only bound if the above is missing */
+    this.kdeDecorationManager = null;
     this.layerShell = null;
     this.shm = null;
     /** screen capture and the eyedropper (screencopy.js); null on GNOME */
@@ -159,6 +162,13 @@ export class WaylandApp extends EventEmitter {
     // defers to it: the pin is read here instead, from the same options.
     await app._beginOutputs(conn, options);
     app.decorationManager = await conn.bind('zxdg_decoration_manager_v1');
+    // The older KDE protocol says the same thing, and some compositors have
+    // only that one. Bound where the standard one is missing, which is the
+    // only time it would be used — a frame the compositor draws beats one
+    // this backend imitates (ssd.js).
+    app.kdeDecorationManager = app.decorationManager
+      ? null
+      : await conn.bind('org_kde_kwin_server_decoration_manager');
     app.layerShell = await conn.bind('zwlr_layer_shell_v1');
     app.shm = await conn.bind('wl_shm');
     app.seat = await WaylandSeat.bind(conn);
@@ -255,6 +265,10 @@ export class WaylandApp extends EventEmitter {
 
   /** After an offscreen render, put the window's backing target back. */
   rebindWindowTarget() {
+    // The framebuffer changes here without any 2d context being told, so
+    // none of them owns the device's state any more and the next one to
+    // draw re-establishes its own (device.js).
+    if (this.gl) releaseDevice(this.gl);
     for (const w of this.windows.values()) {
       if (w._frameSize) {
         w.glctx.bindBacking();

package/src/wayland/backendwindow.js

@@ -18,12 +18,15 @@
 // `wl_surface.frame` callback (or paints straight away for the first frame,
 // which nothing can pace), the callback runs the renderer's paint into the
 // backing target, and the result is copied to a swapchain buffer and
-// committed with the next frame request in the same commit.
+// committed with the next frame request in the same commit. A compositor
+// stops answering those for a surface it is not showing, and the loop then
+// parks with nothing to say for itself — so it is watched (framewatch.js),
+// which is where `presenting` comes from.
 //
-// The frame is drawn here only until a compositor agrees to draw it:
-// where xdg-decoration is offered the window asks for server-side
-// decorations (ssd.js) and, granted them, switches its own off, which the
-// tree sees as the content growing. And a window whose `windowType` is a
+// The frame is drawn here only as a last resort: where either decoration
+// protocol is offered the window asks for server-side decorations (ssd.js)
+// and, granted them, switches its own off, which the tree sees as the
+// content growing. And a window whose `windowType` is a
 // dock, a wallpaper, a notification or a splash is not a toplevel at all
 // where the compositor has layer-shell (layershell.js) — same surface, same
 // loop, no frame.
@@ -33,6 +36,7 @@ import { writeSync, writeFileSync } from 'node:fs';
 import { snapshotPNG } from './readback.js';
 import { WaylandWindow, TOPLEVEL_STATE } from './window.js';
 import { WaylandGLContext } from './glcontext.js';
+import { FrameWatch } from './framewatch.js';
 import { WaylandContext2D } from './context2d.js';
 import { Decorations } from './decorations.js';
 import { appearanceSnapshot } from '../appearance.js';
@@ -122,6 +126,17 @@ export class WaylandBackendWindow extends EventEmitter {
     this._surfaceRaf = [];
     /** rects (content px) a surface or pane changed since the last present */
     this._surfaceDamage = [];
+    /**
+     * The frame loop's liveness (framewatch.js). A compositor is entitled to
+     * stop sending frame callbacks to a surface it is not showing, and that
+     * silence is the only thing that says so — it is not an error, and
+     * nothing above here can see it (#567).
+     */
+    this._frameWatch = new FrameWatch({
+      id: this.id,
+      pending: () => this._hasFrameWork(),
+      onChange: (presenting) => this.emit('presenting', presenting),
+    });
 
     // Frame and content sizes. `attributes.width/height` are what the tree
     // measured, in device pixels of content; the surface adds the frame.
@@ -206,9 +221,14 @@ export class WaylandBackendWindow extends EventEmitter {
         width: surfaceW,
         height: surfaceH,
         parent: app.parentFor(attributes, { toplevelOnly: true })?.wl ?? null,
-        decorations: app.decorationManager
-          ? { manager: app.decorationManager, prefer: this._decorPolicy.prefer }
-          : null,
+        decorations:
+          app.decorationManager || app.kdeDecorationManager
+            ? {
+                manager: app.decorationManager,
+                kdeManager: app.kdeDecorationManager,
+                prefer: this._decorPolicy.prefer,
+              }
+            : null,
       });
     }
     this.wl.scale = scale;
@@ -481,6 +501,15 @@ export class WaylandBackendWindow extends EventEmitter {
     this._armFrame();
   }
 
+  /** Is there a repaint waiting on the next frame? The three ways there can
+   *  be one: the renderer's callbacks, a `<glarea>`'s, and the frame the
+   *  decorations ask for. */
+  _hasFrameWork() {
+    return (
+      this._raf.length > 0 || this._surfaceRaf.length > 0 || this._frameDirty
+    );
+  }
+
   /**
    * Get a frame in flight.
    *
@@ -508,7 +537,14 @@ export class WaylandBackendWindow extends EventEmitter {
     if (this.isDragPreview) return;
     // A closed connection arms nothing: a frame request on it rejects at
     // once, the rejection re-arms, and that loop never yields.
-    if (this._frameArmed || this._destroyed || this.app.conn?.destroyed) return;
+    if (this._destroyed || this.app.conn?.destroyed) return;
+    if (this._frameArmed) {
+      // The repaint rides the frame already in flight — unless that flight is
+      // the compositor's silence, in which case this is the moment the app
+      // started drawing for nobody (framewatch.js).
+      this._frameWatch.workArrived();
+      return;
+    }
     this._frameArmed = true;
     this.wl.whenConfigured
       .then(() => {
@@ -522,8 +558,12 @@ export class WaylandBackendWindow extends EventEmitter {
         }
         const vsync = this.wl.scheduleFrame();
         this.wl.surface.$.commit();
+        this._frameWatch.waiting();
         vsync.then(
-          (t) => this._fireRaf(t),
+          (t) => {
+            this._frameWatch.arrived();
+            this._fireRaf(t);
+          },
           () => this._frameIdle(),
         );
       })
@@ -533,11 +573,34 @@ export class WaylandBackendWindow extends EventEmitter {
   /** The frame is over with nothing presented; run again only if asked. */
   _frameIdle() {
     this._frameArmed = false;
+    // Nothing is outstanding now — which is not the same as being shown, so
+    // the watch stops counting rather than declaring anything.
+    this._frameWatch.idle();
     if (!this._destroyed && (this._raf.length || this._frameDirty)) {
       this._armFrame();
     }
   }
 
+  /**
+   * Is the compositor still scheduling frames for this surface?
+   *
+   * False once a frame callback has gone unanswered for long enough to mean
+   * the surface is not being shown (framewatch.js) — the app's own animation
+   * and simulation are drawing for nobody until this is true again. The tree
+   * reads it through `useWindowState().presenting`, which also folds it into
+   * `visible`; this is the window-object half of that.
+   */
+  get presenting() {
+    return this._frameWatch.presenting;
+  }
+
+  /** Subscribe to it. The X11 and Cocoa windows have no such signal, and
+   *  `windowstate.js` takes the absence of this method as "always true". */
+  onPresentingChange(fn) {
+    this.on('presenting', fn);
+    return () => this.off('presenting', fn);
+  }
+
   /** Translate into the content area and clip to it. */
   _enterContent(ctx) {
     const o = this.contentOrigin;
@@ -630,6 +693,13 @@ export class WaylandBackendWindow extends EventEmitter {
    * time — a background fill reaching under a static scene — the surface's
    * pixels are gone with the repaint, so its node is asked for the frame
    * now, before the present, rather than showing the fill for a frame.
+   *
+   * `restoreGLState()` is here for the foreign GL specifically: a
+   * `<glarea>` draws with entry points nobody is tracking, so the state it
+   * left has to be assumed lost. An *offscreen* surface painted in the
+   * middle of the frame needs nothing said about it — its context and this
+   * one hand the device back and forth on their own (device.js), so a node
+   * that drew into one does not have to know the window has GL state.
    */
   _runSurfaces(ctx, time, wholeFrame) {
     ctx?.flush();
@@ -733,9 +803,14 @@ export class WaylandBackendWindow extends EventEmitter {
           `${damage === 'all' ? 'full' : damage.length + ' rect(s)'}\n`,
       );
     }
+    // The frame request `endFrame` put in this commit is the loop's only
+    // liveness from here on: the compositor answers it when it next shows
+    // this surface, and never if it stops (framewatch.js).
+    this._frameWatch.waiting();
     Promise.resolve(vsync).then(
       (t) => {
         this._presentInFlight = false;
+        this._frameWatch.arrived();
         if (!this._destroyed) this._fireRaf(t);
       },
       () => {
@@ -1111,6 +1186,7 @@ export class WaylandBackendWindow extends EventEmitter {
     if (this._destroyed) return;
     this._destroyed = true;
     this._raf.length = 0;
+    this._frameWatch.stop();
     this.app.dnd?.detach(this);
     this.app.makeCurrent();
     for (const ctx of this._contexts.values()) ctx.destroy?.();

package/src/wayland/connection.js

@@ -66,6 +66,9 @@ export const PROTOCOLS = [
   'tablet-v2',
   'xdg-activation-v1',
   'xdg-decoration-unstable-v1',
+  // the older KDE protocol that does the same job, for the compositors that
+  // have only that one (ssd.js picks between them)
+  'kde-server-decoration',
   'primary-selection-unstable-v1',
   'text-input-unstable-v3',
   'pointer-constraints-unstable-v1',

package/src/wayland/context2d.js

@@ -43,6 +43,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Path2D, Image as NtkImage } from 'ntk';
+import { glDevice } from './device.js';
 import { GlyphAtlas } from './glyphatlas.js';
 import { GLTarget } from './target.js';
 
@@ -203,6 +204,17 @@ function scaleOf(m) {
   return Math.sqrt(Math.abs(m[0] * m[3] - m[1] * m[2])) || 1;
 }
 
+/**
+ * The Render ops a `drawGlyphs` call can name, numbered as XRender numbers
+ * them — the same table the Cocoa backend answers (`src/cocoa/context2d.js`),
+ * so `ctx.Render.PictOp.Over` reads the same on every backend. The op is
+ * ignored here: text composites Over, and for the opaque inks text uses Src
+ * and Over agree.
+ */
+const RENDER = Object.freeze({ PictOp: Object.freeze({ Src: 1, Over: 3 }) });
+
+const clamp01 = (v) => Math.min(1, Math.max(0, Number(v) || 0));
+
 const colorCache = new Map();
 
 /**
@@ -390,13 +402,20 @@ export class WaylandContext2D {
    * @param {object} [opts]
    * @param {object} [opts.fontManager] an ntk FontManager, for `fillText`
    * @param {import('./target.js').GLTarget} [opts.target] where to draw
+   * @param {() => void} [opts.makeCurrent] called before this context takes
+   *   the device back, for an owner that has to make a GL surface current
+   *   first — an offscreen surface, whose context may be drawn through at
+   *   any time, not only inside a window's frame
    */
-  constructor(gl, { fontManager = null, target = null } = {}) {
+  constructor(gl, { fontManager = null, target = null, makeCurrent } = {}) {
     this.gl = gl;
     this.fontManager = fontManager;
+    /** @see ./device.js — the state this context shares with its siblings */
+    this._device = glDevice(gl);
+    this._makeCurrent = makeCurrent ?? null;
     // `TextLayout.draw` opens with `ctx.window.app.display.Render` and reads
     // one constant from it. Satisfy the shape rather than fork the layout.
-    this.window = { app: { display: { Render: { PictOp: { Over: 3 } } } } };
+    this.window = { app: { display: { Render: RENDER } } };
     this.atlas = new GlyphAtlas(gl);
     // Quads already buffered against the atlas must be drawn before the
     // atlas re-lays itself out under them.
@@ -495,8 +514,12 @@ export class WaylandContext2D {
 
   /** Where this context draws. A window's backing, or a surface's target. */
   attach(target) {
-    if (this._target !== target) this._flush();
+    if (this._target === target) return;
+    this._flush();
     this._target = target;
+    // The projection and the bound framebuffer both belonged to the old
+    // target; the next draw re-establishes them against this one.
+    this._release();
   }
 
   get target() {
@@ -509,6 +532,7 @@ export class WaylandContext2D {
    */
   begin(width, height, timestamp = 0) {
     this.init();
+    this._device.owner = this;
     const t = this._target;
     if (t) {
       t.bind();
@@ -540,9 +564,11 @@ export class WaylandContext2D {
   }
 
   /**
-   * The GL state every draw here assumes. `begin()` sets it; a `<glarea>`
-   * that drew in the middle of the frame may have changed any of it, and
-   * `restoreGLState()` puts it back without starting a new frame.
+   * The GL state every draw here assumes: the target bound, the projection
+   * sized to it, and the rest of the device saying what the shader was
+   * written against. `begin()` sets it; `_claim()` sets it again whenever
+   * something else has been drawing — another context, or a `<glarea>`'s
+   * foreign GL — since this one last did.
    */
   _applyState() {
     const gl = this.gl;
@@ -558,14 +584,8 @@ export class WaylandContext2D {
     // Premultiplied alpha throughout — colours are premultiplied on the way
     // in, and the glyph and texture paths both produce premultiplied output.
     gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
-  }
-
-  /** After foreign GL drew — a `<glarea>`'s frame — before drawing again. */
-  restoreGLState() {
-    const gl = this.gl;
-    this._flush();
-    this._applyState();
-    // …and what `begin()` never had to say, because nothing here changes it
+    // …and what a frame of this context's own never has to say, because
+    // nothing here changes it. Foreign GL does.
     if (typeof gl.bindVertexArray === 'function') gl.bindVertexArray(null);
     gl.blendEquation(gl.FUNC_ADD);
     gl.stencilMask(0xff);
@@ -574,6 +594,51 @@ export class WaylandContext2D {
     gl.activeTexture(gl.TEXTURE0);
   }
 
+  /**
+   * Take the device before touching GL (device.js).
+   *
+   * Contexts on this backend share one GLES context, so the framebuffer and
+   * the state a draw needs are whatever the last one to draw left behind.
+   * This is the one place that notices and puts them back — which is what
+   * makes a held offscreen-surface context work the way ntk documents it,
+   * rather than only inside `Surface#render` (#566), and what spares a node
+   * that painted into a surface mid-frame from having to restore the
+   * window's context by hand afterwards.
+   *
+   * Nothing happens in the common case: a property compare against a
+   * context that is already the owner.
+   */
+  _claim() {
+    // Mid stencil-then-cover the state is set up for the pass, not for a
+    // plain batch, and the device cannot have changed hands under it.
+    if (this._device.owner === this || this._stencilling) return;
+    this._device.owner = this;
+    this._makeCurrent?.();
+    this.init();
+    // As `begin()` has it: a target's size *is* the projection.
+    const t = this._target;
+    if (t) {
+      this._width = t.width;
+      this._height = t.height;
+    }
+    this._applyState();
+  }
+
+  /** Give the device up, so the next draw through this context re-takes it. */
+  _release() {
+    if (this._device.owner === this) this._device.owner = null;
+  }
+
+  /** After foreign GL drew — a `<glarea>`'s frame — before drawing again. */
+  restoreGLState() {
+    // Foreign GL leaves no trace in the bookkeeping, so say so and re-take
+    // the device. State first, then the flush: anything still buffered is
+    // drawn under this context's state rather than under what was left.
+    this._release();
+    this._claim();
+    this._flush();
+  }
+
   /** Flush what is buffered without ending the frame. */
   flush() {
     this._flush();
@@ -866,8 +931,29 @@ export class WaylandContext2D {
     this._rect(x, y, w, h, 0, this.strokeStyle, Math.max(0.5, this.lineWidth));
   }
 
-  /** The batched form react-x11 uses for backgrounds and selection bands. */
+  /**
+   * The batched form react-x11 uses for backgrounds and selection bands.
+   *
+   * Three shapes, because all three are in use: `[[x,y,w,h],…]`,
+   * `[{x,y,width,height},…]`, and the flat `[x,y,w,h,x,y,w,h,…]` that
+   * `Render.FillRectangles` takes on the wire. ntk and the Cocoa context
+   * both accept the flat list, so it is what a caller written against
+   * either of them hands us; reading it as one rectangle per element makes
+   * every field `undefined` and draws nothing at all.
+   */
   fillRects(rects) {
+    if (!rects?.length) return;
+    if (typeof rects[0] === 'number') {
+      // a trailing partial rectangle is not one, so stop four short
+      for (let i = 0; i + 3 < rects.length; i += 4) {
+        const x = rects[i];
+        const y = rects[i + 1];
+        const w = rects[i + 2];
+        const h = rects[i + 3];
+        this._rect(x, y, w, h, 0, this.fillStyle, 0);
+      }
+      return;
+    }
     for (const r of rects) {
       const x = r.x ?? r[0];
       const y = r.y ?? r[1];
@@ -1093,6 +1179,10 @@ export class WaylandContext2D {
   _fillPolys(polys, rule, style) {
     const bounds = polysBounds(polys);
     if (!bounds || bounds.w <= 0 || bounds.h <= 0) return;
+    // Before `_fillCoverage`, which cuts its raster to `_width`/`_height`:
+    // on a context that has never opened a frame those are the target's
+    // only once the device has been claimed.
+    this._claim();
     let color = null;
     if (!(style instanceof Gradient)) {
       color = this._color(style);
@@ -1334,6 +1424,7 @@ export class WaylandContext2D {
    * `(img, sx, sy, sw, sh, dx, dy, dw, dh)`, as canvas.
    */
   drawImage(img, ...args) {
+    this._claim();
     const src = this._textureFor(img);
     if (!src) return;
     let sx = 0;
@@ -1421,6 +1512,9 @@ export class WaylandContext2D {
   getImageData(x, y, w, h) {
     this._flush();
     const gl = this.gl;
+    // `readPixels` reads the bound framebuffer, and a blit or another
+    // context may have left it pointing elsewhere since the last draw.
+    this._target?.bind();
     const W = Math.max(0, w | 0);
     const H = Math.max(0, h | 0);
     const raw = new Uint8Array(W * H * 4);
@@ -1543,6 +1637,44 @@ export class WaylandContext2D {
 
   // ---- text -------------------------------------------------------------
 
+  /** ntk's Render extension object, as much of it as glyph runs need. */
+  get Render() {
+    return RENDER;
+  }
+
+  /**
+   * A solid ink for `drawGlyphs`. ntk answers an XRender `Picture` here and
+   * the Cocoa backend the colour itself; this answers the same stand-in
+   * `_stylePicture` builds, so the way ntk documents the call
+   *
+   *     ctx.drawGlyphs(ctx.Render.PictOp.Over,
+   *                    ctx.createSolidPicture(r, g, b, a), runs)
+   *
+   * draws on every backend unchanged. Half the pair — `drawGlyphs` without
+   * this — left every caller that positions its own glyphs (a terminal
+   * grid, a tabular column) feature-detecting, and a feature test that came
+   * back false drew a frame with no text in it rather than throwing (issue
+   * #565).
+   *
+   * The channels are **premultiplied** 0..1, as XRender solids are, which
+   * is the form this context carries colours in — so they pass through
+   * `parseColor` untouched. A channel brighter than the alpha is not a
+   * premultiplied colour; it is clamped down to it, which is the same
+   * colour the Cocoa backend lands on for that input (it un-premultiplies
+   * and clamps to 1).
+   */
+  createSolidPicture(r, g, b, a) {
+    const alpha = clamp01(a);
+    return {
+      color: Object.freeze([
+        Math.min(clamp01(r), alpha),
+        Math.min(clamp01(g), alpha),
+        Math.min(clamp01(b), alpha),
+        alpha,
+      ]),
+    };
+  }
+
   /**
    * ntk's glyph-drawing contract, which is how `TextLayout.draw` reaches a
    * context — and therefore how every `<text>`, `<textinput>` and
@@ -1551,16 +1683,17 @@ export class WaylandContext2D {
    * The signature is XRender's: a `PictOp`, a source `Picture`, and glyph
    * runs already placed at absolute baselines. The op is always `Over` for
    * text and the source is always a solid colour, so what this does is take
-   * the colour back out of the stand-in `_stylePicture` handed over and draw
-   * the runs through the atlas.
+   * the colour back out of the ink handed over (`_inkOf`) and draw the runs
+   * through the atlas.
    *
    * @param {number} op ignored — text is always drawn `Over`
-   * @param {{color?:string}} src what `_stylePicture` returned
+   * @param {object|string|number[]|null} src a `createSolidPicture` ink, a
+   *   `_stylePicture` stand-in, a colour, or null for the fill style
    * @param {Array<{run:object, x:number, y:number}>} positioned
    */
   drawGlyphs(op, src, positioned) {
     if (!Array.isArray(positioned)) return;
-    const color = src?.color ?? this.fillStyle;
+    const color = this._inkOf(src);
     const runs = [];
     for (const p of positioned) {
       const run = p.run;
@@ -1583,6 +1716,22 @@ export class WaylandContext2D {
     return { color };
   }
 
+  /**
+   * The colour a `drawGlyphs` source paints with: a `createSolidPicture`
+   * ink or a `_stylePicture` stand-in (both carry `.color`), a CSS colour
+   * string, a premultiplied `[r, g, b, a]` — or, for anything this context
+   * cannot ink glyphs with (a gradient), the fill style in force. The same
+   * set the Cocoa backend takes, so a caller that skips the picture and
+   * names a colour draws here too.
+   */
+  _inkOf(src) {
+    if (typeof src === 'string' || Array.isArray(src)) return src;
+    const color = src?.color;
+    return typeof color === 'string' || Array.isArray(color)
+      ? color
+      : this.fillStyle;
+  }
+
   get _backgroundPicture() {
     return { color: this.fillStyle };
   }
@@ -1838,6 +1987,11 @@ export class WaylandContext2D {
   }
 
   _flush() {
+    // Before the early return, not after: `clearRect` and `putImageData`
+    // flush, change the blend function and flush again, and the second
+    // flush must not be the one that re-takes the device and puts the
+    // blending back.
+    this._claim();
     if (this._n === 0) return;
     const gl = this.gl;
     const { aPos, aUV, aColor, aParams } = this._loc;
@@ -1929,6 +2083,9 @@ export class WaylandContext2D {
   }
 
   destroy() {
+    // Nothing of this context's is installed any more, and the device
+    // record should not be the one thing still holding on to it.
+    this._release();
     this.atlas.destroy();
     this.masks.destroy();
     if (this._buffer) this.gl.deleteBuffer(this._buffer);