react-x11 2.19.0 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -108,7 +108,7 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.12.0",
+    "@windowkit/appkit": "^0.13.0",
     "@windowkit/wayland": "^3.1.1",
     "@windowkit/win32": "^0.0.3",
     "dbus-native": "^0.15.1",

package/src/cocoa/fonts.js

@@ -5,7 +5,7 @@
 //   fonts.layout(spans, base, { maxWidth, align, lineHeight, maxLines,
 //                               overflow, direction })
 //     -> { width, height, lines, draw(ctx, x, y),
-//          indexAt(x, y), caretPosition(cp) }
+//          indexAt(x, y), caretPosition(cp), coverage({ pad }) }
 //   fonts.match(family, { weight, style }) -> face
 //   fonts.fallbackFor(codepoint, family, { weight, style }) -> face | null
 //
@@ -144,6 +144,25 @@ class CocoaTextLayout {
   caretPosition(cp) {
     return this._native.layoutCaret(this._handle, this._cuOf(cp));
   }
+
+  /**
+   * How much of each device pixel the glyphs cover, one byte a pixel,
+   * without drawing them anywhere (#673) — for text that is drawn where a 2D
+   * context is not, a GL surface's labels. The raster is the layout's box in
+   * whole pixels with `pad` round it, the layout's origin at (pad, pad).
+   *
+   * The bridge's `layoutCoverage`: each glyph's CoreText outline where the
+   * run put it, unrounded, filled once by the signed-area accumulation ntk
+   * rasterizes with, so the X11 engine and this one give the same bytes for
+   * the same outlines — and none of the font smoothing the screen gets. Not
+   * CoreText's glyph rasterizer, which shrinks a small glyph's counters even
+   * with smoothing off. Null on a bridge that predates it (`@windowkit/appkit`
+   * before 0.13.0), so a caller keeps its readback.
+   */
+  coverage({ pad = 0 } = {}) {
+    if (typeof this._native.layoutCoverage !== 'function') return null;
+    return this._native.layoutCoverage(this._handle, pad) ?? null;
+  }
 }
 
 /**

package/src/glnodes.js

@@ -379,8 +379,10 @@ export class GlAreaNode extends Node {
     // `_assignAbs` keeps the object when nothing changed
     const still = this.abs === was;
     const { x, y } = this.abs;
+    const dx = x - was.x;
+    const dy = y - was.y;
     for (const child of this.children) {
-      if (child.isWindow) continue;
+      if (child.isWindow || child._followParent(dx, dy)) continue;
       if (still) this._absolutizeChild(child, x, y, overlay);
       else child.absolutize(x, y);
     }

package/src/node.d.ts

@@ -545,8 +545,21 @@ export declare class Node {
    * coordinates and inside this node. The return says whether the frame is
    * still a blit candidate; the gates that matter close at frame time, and
    * every one of them falls back to repainting `rect`.
+   *
+   * `riders` are other nodes whose pixels in `rect` are part of what moves —
+   * a layer of widgets the element lays out over its own drawing and pans
+   * with it. Each is to move by exactly (dx, dy) in this frame's layout pass
+   * and change nothing else; then it does not decline the blit, and only
+   * what it leaves or reaches outside `rect` is repainted, so keep what it
+   * can paint inside the element (a box that clips it). Anything else it
+   * does is claimed as usual, which declines the blit.
    */
-  scrollContents(rect: Rect, dx: number, dy: number): boolean;
+  scrollContents(
+    rect: Rect,
+    dx: number,
+    dy: number,
+    riders?: Iterable<Node>,
+  ): boolean;
   /**
    * Did anything this node draws change? True damages the whole node, false
    * contributes no damage at all, and the default answers true for any prop

package/src/nodes/layout.js

@@ -5,9 +5,54 @@
 import { Yoga } from '../yoga.js';
 import { callHandler } from '../errors.js';
 import { DAMAGE_SLOP, layoutDiff } from './damage.js';
-import { insetRect } from './rects.js';
+import { insetRect, intersectRects, outerPixels } from './rects.js';
 import { DEV } from './util.js';
 
+/** The parts of `rect` outside `hole`: up to four bands, full width above
+ *  and below, the rest beside. */
+function outside(rect, hole) {
+  const cut = intersectRects(rect, hole);
+  if (!cut) return [rect];
+  const out = [];
+  const right = rect.x + rect.width;
+  const bottom = rect.y + rect.height;
+  if (cut.y > rect.y) {
+    out.push({
+      x: rect.x,
+      y: rect.y,
+      width: rect.width,
+      height: cut.y - rect.y,
+    });
+  }
+  const cutBottom = cut.y + cut.height;
+  if (cutBottom < bottom) {
+    out.push({
+      x: rect.x,
+      y: cutBottom,
+      width: rect.width,
+      height: bottom - cutBottom,
+    });
+  }
+  if (cut.x > rect.x) {
+    out.push({
+      x: rect.x,
+      y: cut.y,
+      width: cut.x - rect.x,
+      height: cut.height,
+    });
+  }
+  const cutRight = cut.x + cut.width;
+  if (cutRight < right) {
+    out.push({
+      x: cutRight,
+      y: cut.y,
+      width: right - cutRight,
+      height: cut.height,
+    });
+  }
+  return out;
+}
+
 export const MEASURE_MODES = [];
 MEASURE_MODES[Yoga.MEASURE_MODE_UNDEFINED] = 'unconstrained';
 MEASURE_MODES[Yoga.MEASURE_MODE_EXACTLY] = 'exactly';
@@ -198,20 +243,200 @@ export class NodeLayout {
     // its own — counts as on screen too
     this._placed = true;
     if (!this.yoga) return;
-    this._assignAbs(
-      originX + this.yoga.getComputedLeft(),
-      originY + this.yoga.getComputedTop(),
-      this.yoga.getComputedWidth(),
-      this.yoga.getComputedHeight(),
-    );
-    if (this.props.onLayout) this._reportLayout();
-    if (this._host !== null) {
-      this._absolutizeHostChildren();
+    const x = originX + this.yoga.getComputedLeft();
+    const y = originY + this.yoga.getComputedTop();
+    const width = this.yoga.getComputedWidth();
+    const height = this.yoga.getComputedHeight();
+    const wasX = this.abs.x;
+    const wasY = this.abs.y;
+    const move = this._beginRigidMove(x, y, width, height);
+    try {
+      this._assignAbs(x, y, width, height);
+      if (this.props.onLayout) this._reportLayout();
+      if (this._host !== null) {
+        this._absolutizeHostChildren();
+      } else {
+        const dx = this.abs.x - wasX;
+        const dy = this.abs.y - wasY;
+        for (const child of this.children) {
+          if (child.isWindow || child._followParent(dx, dy)) continue;
+          child.absolutize(this.abs.x, this.abs.y);
+        }
+      }
+    } finally {
+      if (move) layoutDiff.shift = null;
+    }
+    if (move) this._claimRigidMove(move);
+  }
+
+  /**
+   * A child of a node that moved this pass, which yoga did not lay out
+   * again: its box and everything under it sit exactly where the last pass
+   * put them relative to their parents, so the whole subtree moves by
+   * however far its parent did (`dx`, `dy`) — `_shiftAbs`, the scroll fast
+   * path's translation (issue #405), instead of the walk. Answers whether
+   * it was handled; false means walk it.
+   *
+   * The witness is yoga's has-new-layout flag, the one that fast path
+   * reads: a pass sets it on every node it lays out and on every child of
+   * one, cached or not, so a child it is clear on was not reached, nor was
+   * anything under it. Cleared here when it is found set, just before the
+   * walk that reads what the pass left — no pass runs in between — so the
+   * next move of the same subtree finds it clear. Nothing else pays for
+   * it: a child of a node that did not move is walked as it always was,
+   * and a scroll pane always is, since its flag is its own (and a scroll
+   * moves its children with no pass at all).
+   *
+   * Walking such a subtree read four numbers out of yoga per node and wrote
+   * them back unchanged: the bodies of a graph's cards, fifty widgets deep,
+   * on every step of a pan that moved the one box they sit in.
+   *
+   * A move it rode — the diff's `shift`, where the pixels are carried —
+   * claims nothing, as the walk would not have. A move of its own claims
+   * where the subtree's pixels were and where they are, which is what the
+   * walk's claims came to.
+   */
+  _followParent(dx, dy) {
+    if (dx === 0 && dy === 0) return false;
+    const yoga = this.yoga;
+    if (!yoga || !this._placed || this.isScroller?.()) return false;
+    if (yoga.hasNewLayout()) {
+      yoga.markLayoutSeen();
+      return false;
+    }
+    const sink = layoutDiff.sink;
+    const shift = layoutDiff.shift;
+    if (
+      sink &&
+      !(shift && shift.x === dx && shift.y === dy) &&
+      !this.hidden &&
+      this.style?.display !== 'none'
+    ) {
+      const reach = this.paintBounds();
+      // where the walk's `_assignAbs` puts the near end: after the shift a
+      // scroll blit is about to make, when one is riding (issue #398)
+      sink(
+        shift
+          ? {
+              x: reach.x + shift.x,
+              y: reach.y + shift.y,
+              width: reach.width,
+              height: reach.height,
+            }
+          : reach,
+        this,
+      );
+      sink(
+        {
+          x: reach.x + dx,
+          y: reach.y + dy,
+          width: reach.width,
+          height: reach.height,
+        },
+        this,
+      );
+    }
+    this._shiftAbs(dx, dy);
+    return true;
+  }
+
+  /**
+   * The start of a move that changed nothing but where this subtree sits:
+   * the same size, somewhere else, in a bounded frame's layout diff that no
+   * shift is riding already. The walk below then runs with the diff's
+   * `shift` set to the move, so every descendant that lands where it was
+   * plus the move claims nothing — and one that lands anywhere else claims
+   * both ends of its own, as under a scroll blit (issue #398).
+   *
+   * What the subtree is owed instead is two claims: where its pixels were,
+   * and where they went (`_claimRigidMove`). Walked node by node, a moved
+   * card of fifty widgets claimed a hundred rects, the frame's cap merged
+   * them into their box, and the box of pieces reaching past every clipping
+   * ancestor was the whole window — a panned layer of such cards made every
+   * step of the pan a full repaint, header and all.
+   *
+   * Null when the move is not of that kind, or no diff is listening; the
+   * walk is then the plain one.
+   */
+  _beginRigidMove(x, y, width, height) {
+    if (!layoutDiff.sink || layoutDiff.shift) return null;
+    const old = this.abs;
+    if (width !== old.width || height !== old.height) return null;
+    if (x === old.x && y === old.y) return null;
+    if (!(old.width > 0 && old.height > 0)) return null;
+    if (this.hidden || this.style?.display === 'none') return null;
+    // a placement moves it again after the walk (src/nodes/position.js)
+    if (this.root?._placedNodes?.has(this)) return null;
+    const shift = { x: x - old.x, y: y - old.y };
+    // before anything under it moves: every pixel it had
+    const was = this.paintBounds();
+    layoutDiff.shift = shift;
+    // Carried by an element's blit (`scrollContents`'s riders), when the
+    // move is the blit's own: then the pixels inside its rect are moved
+    // for it, and only what lies outside is owed.
+    const contents = this._ridesBlitOf?._pendingBlitContents;
+    const carried =
+      contents && contents.dx === shift.x && contents.dy === shift.y
+        ? contents.rect
+        : null;
+    return { sink: layoutDiff.sink, was, shift, carried };
+  }
+
+  /**
+   * Both ends of a rigid move, each clipped to what the clipping ancestors
+   * let reach the surface. The far end is the near one moved: every
+   * descendant that rode the move is inside it, and one that did not has
+   * claimed where it went itself.
+   *
+   * Named for the node that moved, which is what sends each claim to the
+   * lists that paint it (`_paneReach`): the panes alone inside a
+   * `<glarea>`, both for a subtree holding one.
+   */
+  _claimRigidMove({ sink, was, shift, carried }) {
+    const root = this.root;
+    const to = {
+      x: was.x + shift.x,
+      y: was.y + shift.y,
+      width: was.width,
+      height: was.height,
+    };
+    if (carried) {
+      // Straight to the window's list rather than through the diff, whose
+      // claims read as "this frame is not a pure scroll": what is outside
+      // the rect is beside it, and the blit stands.
+      const cap = root._damageRectCap();
+      for (const end of [was, to]) {
+        const clipped = this._clippedByAncestors(end);
+        if (!clipped) continue;
+        for (const piece of outside(clipped, carried)) {
+          root._claimLayoutMove(piece, this, cap);
+        }
+      }
       return;
     }
-    for (const child of this.children) {
-      if (!child.isWindow) child.absolutize(this.abs.x, this.abs.y);
+    const from = this._clippedByAncestors(was);
+    if (from) sink(from, this);
+    const at = this._clippedByAncestors(to);
+    if (at) sink(at, this);
+  }
+
+  /**
+   * `rect` less whatever the ancestors that clip their children cut away,
+   * up to the window: pixels outside one never reach the surface, so a
+   * claim of them repaints what cannot change. Null when nothing is left.
+   * Each clip is the whole pixels the ancestor's box touches — its clip
+   * antialiases a fractional edge over the pixel it cuts, and on a box on
+   * whole pixels cuts exactly; a clip it skips is one nothing inside
+   * reaches (`_childrenCanOverflow`).
+   */
+  _clippedByAncestors(rect) {
+    let out = rect;
+    for (let n = this.parent; n && out; n = n.parent) {
+      if (n.isWindow) break;
+      if (!n.clipsChildren()) continue;
+      out = intersectRects(out, outerPixels(n.abs));
     }
+    return out;
   }
 
   /**

package/src/nodes/node.js

@@ -140,6 +140,9 @@ export class Node {
     // palette with one against the app's own — and none of those is a
     // *change* the user saw, so no transition may start from it.
     this._placed = false;
+    // the element whose pending `scrollContents` carries this node's pixels
+    // this frame (src/nodes/scrollblit.js), or null
+    this._ridesBlitOf = null;
     // the loops this node's style declares, whether or not they are running
     this._loops = null;
     // `resolvedTextStyle()`'s cache: this node's own text style over what it
@@ -623,8 +626,12 @@ export class Node {
       // subtree here, before and after, would be the repaint the overlay
       // exists to skip — and the pass claims both ends of the move itself
       // whenever the overlay cannot move the pixels.
+      //
+      // …and so is a node an element's pan carries (`scrollContents`'s
+      // riders): its pixels move with the region the frame blits, and the
+      // pass claims what they leave outside it (src/nodes/layout.js).
       if (
-        this.parent?.isGlArea &&
+        (this.parent?.isGlArea || this._ridesBlitOf !== null) &&
         moved &&
         !this.paintChanged(newProps, prev)
       ) {

package/src/nodes/rects.js

@@ -34,6 +34,19 @@ export function innerPixels(rect) {
   return { x, y, width: right - x, height: bottom - y };
 }
 
+/** The whole pixels `rect` touches — a fractional edge taken whole, which is
+ * where antialiasing can put ink. */
+export function outerPixels(rect) {
+  const x = Math.floor(rect.x);
+  const y = Math.floor(rect.y);
+  return {
+    x,
+    y,
+    width: Math.ceil(rect.x + rect.width) - x,
+    height: Math.ceil(rect.y + rect.height) - y,
+  };
+}
+
 /** The overlap of two rects, or null when they have none. */
 export function intersectRects(a, b) {
   const x = Math.max(a.x, b.x);

package/src/nodes/scrollable.js

@@ -144,14 +144,28 @@ export const Scrollable = (Base) =>
     absolutize(originX, originY) {
       this._placed = true;
       if (!this.yoga) return;
-      this._assignAbs(
-        originX + this.yoga.getComputedLeft(),
-        originY + this.yoga.getComputedTop(),
-        this.yoga.getComputedWidth(),
-        this.yoga.getComputedHeight(),
-      );
-      if (this.props.onLayout) this._reportLayout();
-      this._absolutizeChildren(this.abs.x, this.abs.y);
+      const x = originX + this.yoga.getComputedLeft();
+      const y = originY + this.yoga.getComputedTop();
+      const width = this.yoga.getComputedWidth();
+      const height = this.yoga.getComputedHeight();
+      // a box that moved and changed nothing else claims where it was and
+      // where it went, once — not once per node inside it (`Node`'s)
+      const wasX = this.abs.x;
+      const wasY = this.abs.y;
+      const move = this._beginRigidMove(x, y, width, height);
+      try {
+        this._assignAbs(x, y, width, height);
+        if (this.props.onLayout) this._reportLayout();
+        this._absolutizeChildren(
+          this.abs.x,
+          this.abs.y,
+          this.abs.x - wasX,
+          this.abs.y - wasY,
+        );
+      } finally {
+        if (move) layoutDiff.shift = null;
+      }
+      if (move) this._claimRigidMove(move);
     }
 
     /**
@@ -159,8 +173,11 @@ export const Scrollable = (Base) =>
      * Split out of `absolutize` because a `<window>` writes its own `abs`
      * during flush and then walks its children from (0, 0) — the same walk,
      * reached by a different route.
+     *
+     * `dx`/`dy` is how far this box moved in this pass, which is how far a
+     * child yoga did not lay out again moves with it (`_followParent`).
      */
-    _absolutizeChildren(originX, originY) {
+    _absolutizeChildren(originX, originY, dx = 0, dy = 0) {
       if (!this.isScroller()) {
         // a layout host's children go where its algorithm put them
         if (this._host !== null) {
@@ -168,7 +185,8 @@ export const Scrollable = (Base) =>
           return;
         }
         for (const child of this.children) {
-          if (!child.isWindow) child.absolutize(originX, originY);
+          if (child.isWindow || child._followParent(dx, dy)) continue;
+          child.absolutize(originX, originY);
         }
         return;
       }

package/src/nodes/scrollblit.js

@@ -20,6 +20,7 @@ import {
   cornerSquaresOverlap,
   rectsOverlap,
 } from './rects.js';
+import { isPaintedColor } from './boxpaint.js';
 import { scrollbarTrackRect } from './scrollbars.js';
 import { debugPaint } from './window/debugpaint.js';
 
@@ -336,11 +337,22 @@ export class NodeScrollBlit {
    * and claims it as ordinary damage. Those claims land beside the rect and
    * the frame stays a blit.
    *
+   * `riders` are the other way round: nodes that are not this one whose
+   * pixels in `rect` are part of what moves — a layer of widgets an element
+   * lays out over its own drawing and pans with it (a graph's node bodies).
+   * Each is to move by exactly (dx, dy) in this frame's layout pass and to
+   * change nothing else. Doing that, it does not decline the blit by being
+   * over the rect, its commit claims nothing, and its move claims only
+   * what it leaves or reaches outside the rect (`_claimRigidMove`) — so
+   * keep what it can paint inside the element's box, a box that clips it
+   * being the way. Doing anything else, it is claimed like any other node,
+   * which declines the blit; the rect then repaints, riders and all.
+   *
    * Returns whether the frame is still a blit candidate. The real answer
    * arrives as `paintDamage()`, because most of the gates cannot be decided
    * until the frame closes; a `false` here is only the ones that can.
    */
-  scrollContents(rect, dx, dy) {
+  scrollContents(rect, dx, dy, riders) {
     const root = this.root;
     if (
       !root ||
@@ -403,6 +415,13 @@ export class NodeScrollBlit {
     // coalescing scrollTo gets from recording an origin
     state.dx += dx;
     state.dy += dy;
+    if (riders) {
+      for (const rider of riders) {
+        if (!rider || rider === this || rider.destroyed) continue;
+        (state.riders ??= new Set()).add(rider);
+        rider._ridesBlitOf = this;
+      }
+    }
     this._pendingBlitFrom ??= BLIT_CONTENTS;
     (root._pendingScrolls ??= new Set()).add(this);
     // ...and the claim about to be recorded is the shift itself, not a
@@ -426,15 +445,34 @@ export class NodeScrollBlit {
    * own, leave `_blitKeptDamage` a damage rect many times the viewport to
    * refuse. Null when the clip left nothing.
    *
-   * Only while a blit is pending — outside that this is `paintBounds()` and
-   * one property read. Clipping every claim to every clipping ancestor
-   * would be correct too, and is a bigger change than the frame this is
-   * about.
+   * And clipped to every other clipping ancestor too, for the same reason
+   * without the blit: a claim past an `overflow: 'hidden'` box repaints
+   * pixels nothing inside it can reach. A layer of cards panned inside a
+   * clipped graph pane reaches past the pane on every side, and its
+   * claims, unclipped, were the whole window.
    */
   _claimBounds() {
     const bounds = this.paintBounds();
     const sv = this._blitViewport();
-    return sv ? intersectRects(bounds, sv.paintBounds()) : bounds;
+    const clipped = sv ? intersectRects(bounds, sv.paintBounds()) : bounds;
+    return clipped && this._clippedByAncestors(clipped);
+  }
+
+  /**
+   * Whether this node puts no pixels of its own on the surface — a plain
+   * box with no fill, border, shadow or outline, holding what is under it
+   * and nothing more. Conservative: anything but a box answers false.
+   */
+  _paintsNothingOwn() {
+    if (this.kind !== 'box' || this.isScroller?.()) return false;
+    const style = this.style ?? EMPTY_STYLE;
+    if (isPaintedColor(style.backgroundColor) || style.backgroundImage) {
+      return false;
+    }
+    if (style.opacity !== undefined && style.opacity < 1) return false;
+    if (this._outlineExtent() > 0 || this._shadowExtent() > 0) return false;
+    const bw = resolveBorderWidths(style, this.direction);
+    return !(bw.top > 0 || bw.right > 0 || bw.bottom > 0 || bw.left > 0);
   }
 
   /** The scroll container above this node that is waiting to blit, if there
@@ -473,6 +511,10 @@ export class WindowScrollBlit {
     const contents = nodes[0]._pendingBlitContents;
     const ledger = nodes[0]._blitLedger;
     for (const n of nodes) {
+      // the pass that needed them is over: a rider is a rider for a frame
+      for (const rider of n._pendingBlitContents?.riders ?? []) {
+        if (rider._ridesBlitOf === n) rider._ridesBlitOf = null;
+      }
       n._pendingBlitFrom = null;
       n._pendingBlitContents = null;
       n._blitLedger = null;
@@ -801,7 +843,13 @@ export class WindowScrollBlit {
    * balloon back towards the whole viewport. With no bars the L is two
    * disjoint rects and stays two.
    */
-  _applyContentsBlit(node, { rect: vp, dx, dy }, width, height, target) {
+  _applyContentsBlit(
+    node,
+    { rect: vp, dx, dy, riders },
+    width,
+    height,
+    target,
+  ) {
     // only a whole-pixel shift of a whole-pixel region is a copy
     if (!isIntegerRect(vp)) return;
     if (!Number.isInteger(dx) || !Number.isInteger(dy)) return;
@@ -870,7 +918,7 @@ export class WindowScrollBlit {
     ) {
       return;
     }
-    if (!this._scrollBlitSafe(node, shifted, target.top)) return;
+    if (!this._scrollBlitSafe(node, shifted, target.top, riders)) return;
     // the element's deltas are already how far the pixels moved, the sense
     // scrollRegion takes (0 + x rather than x: a caller's -0 would survive
     // into request buffers and test comparisons)
@@ -954,7 +1002,7 @@ export class WindowScrollBlit {
    * only its own children — what the window draws under the surface was
    * never in the pane's pixels.
    */
-  _scrollBlitSafe(scroller, vp, top = this) {
+  _scrollBlitSafe(scroller, vp, top = this, riders = null) {
     // the window itself scrolls: everything inside it *is* the scrolled
     // content, so there is nothing that could be dragged along
     if (scroller === this) return true;
@@ -1012,7 +1060,14 @@ export class WindowScrollBlit {
         // be dragged along — a pulsing toast over a list is what promotion
         // is for, and this is the half of it that keeps the pan a blit.
         if (child._promoted) continue;
-        if (rectsOverlap(child._subtreeBounds(), vp)) return false;
+        // …and a node the blit carries has pixels that move with it
+        // (`scrollContents`'s riders)
+        if (riders?.has(child)) continue;
+        if (!rectsOverlap(child._subtreeBounds(), vp)) continue;
+        // A box that paints nothing of its own is its children, and as
+        // safe as they are: the box that clips a rider to its element.
+        if (child._paintsNothingOwn() && check(child)) continue;
+        return false;
       }
       return true;
     };

package/src/win32/fonts.js

@@ -154,6 +154,25 @@ class Win32TextLayout {
     return this._native.layoutCaret(this._handle, this._cuOf(cp));
   }
 
+  /**
+   * How much of each device pixel the glyphs cover, one byte a pixel,
+   * without drawing them anywhere (#673) — for text that is drawn where a 2D
+   * context is not, a GL surface's labels. The raster is the layout's box in
+   * whole pixels with `pad` round it, the layout's origin at (pad, pad).
+   *
+   * DirectWrite's own glyph-run analysis rather than a surface read back:
+   * grayscale, grid fit off, and none of the gamma or enhanced contrast
+   * Direct2D gives text it blends — the outlines' coverage, which is what a
+   * distance field is made from. Null on a bridge that predates it
+   * (`@windowkit/win32` before `layoutCoverage`), so a caller keeps its
+   * readback.
+   */
+  coverage({ pad = 0 } = {}) {
+    if (this._handle == null) return null;
+    if (typeof this._native.layoutCoverage !== 'function') return null;
+    return this._native.layoutCoverage(this._handle, pad) ?? null;
+  }
+
   _cuOf(cp) {
     this._offsets ??= codeUnitOffsets(this._text);
     const at = Math.max(0, Math.min(this._offsets.length - 1, cp));