react-x11 2.41.1 → 2.43.0

package/package.json

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

package/src/cocoa/panehost.js

@@ -32,11 +32,18 @@ const ASKED_KEPT = 16;
 const GESTURE_GAP_MS = 500;
 
 /** How far inside the budget a frame of a pane that fell behind has to
- *  come for its frames to be anchored again (`_answered`): a pane whose
- *  frames come near the budget keeps one look rather than taking the
- *  other at every frame. */
+ *  come for its frames to be shown at their size again (`_answered`): a
+ *  pane whose frames come near the budget keeps one look rather than taking
+ *  the other at every frame. */
 const KEPT_UP = 0.75;
 
+/** How much of a frame's last pixel is carried over the layer past it
+ *  (`_edgeProps`): its middle, a hundredth of a pixel wide. A centre the
+ *  whole pixel wide stretches what the filter makes of it and the pixel
+ *  before it, a blend of the two ramped across the gap, and Core Animation
+ *  takes a centre of no width for none. */
+const EDGE_SLIVER = 0.01;
+
 /** One shared surface on glass: a sublayer of a window's root layer, its
  * contents the IOSurface the pane last presented into it. */
 class PaneLayer {
@@ -51,15 +58,18 @@ class PaneLayer {
     });
     this.destroyed = false;
     this._rect = null;
-    // How the frame the layer holds sits in it while one of the size the
-    // layer was just given is on its way (`_gravityNow`): the gravity set,
-    // Core Animation's own until one is, the sizes asked of the pane with
-    // when each was asked, and whether the pane has fallen behind them.
-    this._gravity = 'resize';
+    // How the frame the layer holds is shown while one of the size the
+    // layer was just given is on its way (`_anchoredNow`, `_edgeProps`):
+    // the sizes asked of the pane with when each was asked, whether the
+    // pane has fallen behind them, the size of the frame it holds, and the
+    // contents rects last set — Core Animation's own, the whole, until any
+    // are.
     this._contentsScale = null;
     this._asked = [];
     this._askedAt = null;
     this._behind = false;
+    this._frame = null;
+    this._edgeKey = `${null}|${null}`;
     // when a frame last answered a size, and how many frames in a row came
     // later than the budget (`_answered`)
     this._answeredAt = -Infinity;
@@ -67,22 +77,21 @@ class PaneLayer {
   }
 
   /**
-   * The gravity a pane's last frame sits in its layer by, until a frame of
-   * the layer's new size lands. The host gives the layer its new size the
-   * moment the window lays out, and the pane's frame of that size comes a
-   * pane frame later: Core Animation's default, `resize`, stretches the
-   * frame it has to the new bounds meanwhile, and a page's left column was
-   * drawn scaled a little at every step of a window dragged wider, and then
-   * at its size again. A pane that keeps up has its frame anchored at the
-   * top left instead, at its size, what it does not cover yet showing the
-   * window under it for a pane frame; one that falls behind the budget is
-   * stretched, which is the better picture for the long wait — a pane
-   * repainting at three frames a second shows a squeezed page, not a page
-   * and a growing strip. The budget is the window's live-resize handshake's
+   * Whether a pane's last frame is shown at its size in its layer until a
+   * frame of the layer's new size lands, or stretched to it. The host gives
+   * the layer its new size the moment the window lays out, and the pane's
+   * frame of that size comes a pane frame later: Core Animation stretches
+   * the frame it has to the new bounds meanwhile, and a page's left column
+   * was drawn scaled a little at every step of a window dragged wider, and
+   * then at its size again. A pane that keeps up has its frame shown at its
+   * size instead, its edge carried over what it does not cover yet
+   * (`_edgeProps`); one that falls behind the budget is stretched, which is
+   * the better picture for the long wait — a pane repainting at three
+   * frames a second shows a squeezed page, not a page and a smeared strip.
+   * The budget is the window's live-resize handshake's
    * (`createRoot({ cocoa: { resizeWait } })`), how long a frame of a new
    * size may take before the old one is shown in its place: 0 stretches
-   * always, as before. A bridge that predates `contentsGravity` ignores it,
-   * and stretches.
+   * always, as before.
    *
    * Behind is a pane whose frames come later than the budget, not one with
    * a size waiting that long. `<Frame>` sends a pane the newest size once
@@ -91,38 +100,84 @@ class PaneLayer {
    * waits until a frame of a later one lands, two pane frames at most. A
    * page that painted in 27 ms answered every size it was sent in 31, and
    * still had one 52 ms old at every step of the drag — so its layer was
-   * stretched at every step and anchored again at every frame, the page
-   * scaling and coming back thirty times a second. Here a size waiting
-   * longer than the budget counts only when no frame has answered any
-   * size in that time, which is a pane that stopped, and a frame that
-   * lands decides the rest (`_answered`).
+   * stretched at every step and shown at its size again at every frame, the
+   * page scaling and coming back thirty times a second. Here a size waiting
+   * longer than the budget counts only when no frame has answered any size
+   * in that time, which is a pane that stopped, and a frame that lands
+   * decides the rest (`_answered`).
    */
-  _gravityNow() {
+  _anchoredNow() {
     const budget = this.app._resizeWait ?? RESIZE_WAIT_MS;
-    if (!(budget > 0)) return 'resize';
+    if (!(budget > 0)) return false;
     // a size asked longer ago than the budget, and no frame of any since
     const oldest = this._asked[0];
     if (oldest && now() - Math.max(oldest.at, this._answeredAt) > budget) {
       this._behind = true;
     }
-    return this._behind ? 'resize' : 'topLeft';
+    return !this._behind;
   }
 
-  /** The props that set the gravity, where it changed. */
-  _gravityProps() {
-    const gravity = this._gravityNow();
-    if (gravity === this._gravity) return null;
-    this._gravity = gravity;
-    // a frame anchored and larger than the layer would hang out of it
-    return { contentsGravity: gravity, masksToBounds: gravity !== 'resize' };
+  /**
+   * The props that show the frame the layer holds in bounds that are not
+   * its size, where they changed. At its size and from the top left, as a
+   * page sits in a window: an axis the layer shrank on is cropped
+   * (`contentsRect`), and on one it grew on the frame's last pixel is
+   * carried over the rest (`contentsCenter`, the part of the contents that
+   * stretches while everything else keeps its size) — the last column
+   * across a window dragged wider, the last row down one dragged taller,
+   * and the corner pixel into the corner. Both rects are the whole when
+   * the frame is stretched, and when it is the layer's size.
+   *
+   * Anchored by gravity alone, the strip the frame did not cover showed
+   * whatever was under the pane, which is the `<Frame>`'s background: in
+   * the browser example's dark mode a dark band 14 to 38 points wide down
+   * the page's right edge, at every step of a fast drag. A page's edge is
+   * mostly its background, so its last pixels continue it: Zen Garden's
+   * about page has a vertical gradient there, which its last column carries
+   * on exactly, where one colour read off the edge put a flat band across
+   * it, three times as far from the page. Where the edge cuts through the
+   * page's content — the bottom row, in a window dragged taller, usually
+   * crosses a line of text — the glyphs run down the strip in thin lines
+   * for the pane frame it lasts, where the settled page has its next line
+   * of text: as far from it, measured, as the flat colour. A bridge that
+   * predates the rects ignores them, and stretches.
+   */
+  _edgeProps() {
+    const frame = this._frame;
+    const rect = this._rect;
+    let crop = null;
+    let edge = null;
+    if (frame && rect && this._anchoredNow()) {
+      const w = Math.min(frame.width, rect.width);
+      const h = Math.min(frame.height, rect.height);
+      if (w < frame.width || h < frame.height) {
+        crop = [0, 0, w / frame.width, h / frame.height];
+      }
+      // in the shown part's own unit square; an axis that did not grow is
+      // all centre, stretched by one
+      const wider = rect.width > w;
+      const taller = rect.height > h;
+      if (wider || taller) {
+        edge = [
+          wider ? (w - 0.5) / w : 0,
+          taller ? (h - 0.5) / h : 0,
+          wider ? EDGE_SLIVER / w : 1,
+          taller ? EDGE_SLIVER / h : 1,
+        ];
+      }
+    }
+    const key = `${crop}|${edge}`;
+    if (key === this._edgeKey) return null;
+    this._edgeKey = key;
+    return { contentsRect: crop, contentsCenter: edge };
   }
 
   /**
    * The props that say how many of the pane's pixels make a point of the
    * layer, where that changed: the window's scale, which the pane draws
-   * at. A frame stretched to the bounds never asked, and one anchored at
-   * its size is shown at it — pixels over `contentsScale` points, so at
-   * the default of 1 a page at 2x came out twice its size.
+   * at. A frame stretched to the bounds never asked, and one shown at its
+   * size is shown at it — pixels over `contentsScale` points, so at the
+   * default of 1 a page at 2x came out twice its size.
    */
   _scaleProps() {
     const scale = this.wnd.scale ?? 1;
@@ -137,7 +192,7 @@ class PaneLayer {
    * the budget put the pane behind, and one well inside it — `KEPT_UP` of
    * it — brings it back: a frame the collector held up stretches nothing,
    * and a pane whose frames come near the budget is not stretched and
-   * anchored by turns.
+   * shown at its size by turns.
    */
   _answered(width, height) {
     const asked = this._asked;
@@ -202,7 +257,7 @@ class PaneLayer {
         zPosition: 1e7,
         hidden: false,
         ...this._scaleProps(),
-        ...this._gravityProps(),
+        ...this._edgeProps(),
       });
     } finally {
       native.txCommit();
@@ -230,22 +285,28 @@ class PaneLayer {
    */
   present(iosurfaceId, size = null) {
     if (this.destroyed) return false;
+    const native = this._native;
+    // The frame and the rects that show it in one transaction: a frame of
+    // a new size shown by the last one's rects is cropped or carried over
+    // by the wrong amount for a refresh.
+    native.txBegin({ disableActions: true });
     try {
-      this._native.setLayerContentsIOSurface(this.layer, iosurfaceId);
-    } catch (err) {
-      if (!/IOSurfaceLookup/.test(err?.message ?? '')) throw err;
-      return false;
-    }
-    // how long the pane took to a frame of a size it was asked for, which
-    // is what the gravity follows (`_gravityNow`)
-    if (size) {
-      this._answered(size.width, size.height);
-      const gravity = this._gravityProps();
-      if (gravity) {
-        withoutActions(this._native, () =>
-          this._native.setLayerProps(this.layer, gravity),
-        );
+      try {
+        native.setLayerContentsIOSurface(this.layer, iosurfaceId);
+      } catch (err) {
+        if (!/IOSurfaceLookup/.test(err?.message ?? '')) throw err;
+        return false;
       }
+      // how long the pane took to a frame of a size it was asked for, which
+      // is what decides how the next is shown (`_anchoredNow`)
+      if (size) {
+        this._answered(size.width, size.height);
+        this._frame = { width: size.width, height: size.height };
+        const edge = this._edgeProps();
+        if (edge) native.setLayerProps(this.layer, edge);
+      }
+    } finally {
+      native.txCommit();
     }
     return true;
   }

package/src/cocoa/sprites.js

@@ -39,6 +39,17 @@
 // clip with round corners that a square ancestor cuts again is a box of its
 // own inside a box of the square one's.
 //
+// Or a part is its **shadows** alone (`shadows`): CSS's outer box-shadow,
+// which its element would blur a pixel at a time and the render server
+// draws on the GPU. Each is a layer that casts it — the shape, its corners
+// rounded, moved clear of what shows and its shadow offset back by as much,
+// so that no spread shows the shape itself — in a box that shows everything
+// but the part's own rect, as an outer shadow is never drawn under the box
+// that casts it. Core Animation's `shadowRadius` is the Gaussian's
+// deviation, which CSS makes half the blur radius: a glow of 200 CSS pixels
+// is a radius of 100 points, and measured against `<Html>`'s own shadow a
+// level apart. Their blur, colour and offset animate there too.
+//
 // A part may be inside another of its element's (`parent`): a spinner in a
 // card that fades. Its layer is lifted inside the parent's, so it fades,
 // turns and is cut with it, and the parent's raster leaves it out — the
@@ -134,18 +145,53 @@ const isCurve = (t) =>
     t[2] >= 0 &&
     t[2] <= 1);
 
+const isColor = (c) => Array.isArray(c) && c.length === 4 && c.every(finite);
+
+const isPair = (p) => Array.isArray(p) && p.length === 2 && p.every(finite);
+
+const isBlur = (v) => finite(v) && v >= 0;
+
+// what each animated property's keyframes are
+const VALUE_OF = {
+  opacity: finite,
+  transform: isMatrix,
+  shadowBlur: isBlur,
+  shadowColor: isColor,
+  shadowOffset: isPair,
+};
+
+const SHADOW_PROPERTIES = new Set([
+  'shadowBlur',
+  'shadowColor',
+  'shadowOffset',
+]);
+
+const isShadow = (sh) =>
+  sh != null &&
+  isRect(sh.rect) &&
+  isColor(sh.color) &&
+  (sh.radius === undefined || isBlur(sh.radius)) &&
+  (sh.x === undefined || finite(sh.x)) &&
+  (sh.y === undefined || finite(sh.y)) &&
+  (sh.blur === undefined || isBlur(sh.blur));
+
+/** Is `sprite` its shadows alone? */
+const castsOnly = (sprite) => Array.isArray(sprite.shadows);
+
 /** Is `a` an animation the bridge will take as it is — so that a bad one
  *  is refused here rather than thrown from inside a frame? */
 function isAnimation(a) {
   if (a == null || typeof a.id !== 'string') return false;
-  if (a.property !== 'opacity' && a.property !== 'transform') return false;
+  const value = Object.hasOwn(VALUE_OF, a.property)
+    ? VALUE_OF[a.property]
+    : null;
+  if (!value) return false;
   if (!finite(a.duration) || !(a.duration > 0)) return false;
   const values = a.values;
   if (!Array.isArray(values) || values.length < 2) return false;
   // an element hands the same keyframes over from frame to frame: they
   // are read once
   if (CHECKED.get(values) !== a.property) {
-    const value = a.property === 'opacity' ? finite : isMatrix;
     if (!values.every(value)) return false;
     CHECKED.set(values, a.property);
   }
@@ -180,13 +226,22 @@ function isAnimation(a) {
 function isSprite(sprite) {
   if (sprite == null || typeof sprite.key !== 'string') return false;
   if (!isRect(sprite.rect)) return false;
-  if (
+  const shadows = sprite.shadows;
+  if (shadows !== undefined) {
+    // its shadows alone: nothing painted, nothing shown
+    if (sprite.paint !== undefined || sprite.contents != null) return false;
+    if (!Array.isArray(shadows) || shadows.length === 0) return false;
+    if (!shadows.every(isShadow)) return false;
+  } else if (
     sprite.contents != null
       ? sprite.paint !== undefined
       : typeof sprite.paint !== 'function'
   ) {
     return false;
   }
+  if (sprite.rectRadius !== undefined && !isBlur(sprite.rectRadius)) {
+    return false;
+  }
   if (sprite.reach !== undefined && !isRect(sprite.reach)) return false;
   if (sprite.clip !== undefined && !isRect(sprite.clip)) return false;
   if (sprite.parent !== undefined && typeof sprite.parent !== 'string') {
@@ -217,6 +272,14 @@ function isSprite(sprite) {
     if (!Array.isArray(animations) || !animations.every(isAnimation)) {
       return false;
     }
+    // a shadow's animation is of one of the part's shadows
+    for (const a of animations) {
+      if (!SHADOW_PROPERTIES.has(a.property)) continue;
+      const i = a.shadow ?? 0;
+      if (!Number.isInteger(i) || i < 0 || !(i < (shadows?.length ?? 0))) {
+        return false;
+      }
+    }
   }
   return true;
 }
@@ -280,6 +343,63 @@ function unionRect(a, b) {
   };
 }
 
+/**
+ * How far past its rect a shadow blurred by `blur` shows: three of its
+ * deviations, half the blur each (CSS Backgrounds 3, 7.1.1), past which the
+ * tail is a fraction of a level; and a pixel more for the antialiased edge
+ * of the shape.
+ */
+const shadowReach = (blur) => Math.ceil(1.5 * blur) + 1;
+
+// where a shadow part's shadows can reach, by its shadows and keyframes
+const SHADOW_REACH = new WeakMap();
+
+/**
+ * What a part draws, untransformed: its `reach`, or its `rect` — and for a
+ * part that is its shadows, everywhere they can be through every keyframe
+ * of their blur and offset, with its own `reach` if it gives one.
+ */
+function reachOf(sprite) {
+  if (!castsOnly(sprite)) return sprite.reach ?? sprite.rect;
+  const shadows = sprite.shadows;
+  const animations = sprite.animations ?? [];
+  const kept = SHADOW_REACH.get(shadows);
+  if (kept && kept.animations === animations && kept.reach === sprite.reach) {
+    return kept.box;
+  }
+  let box = sprite.reach ?? null;
+  for (let i = 0; i < shadows.length; i++) {
+    const sh = shadows[i];
+    let blur = sh.blur ?? 0;
+    let x0 = sh.x ?? 0;
+    let x1 = x0;
+    let y0 = sh.y ?? 0;
+    let y1 = y0;
+    for (const a of animations) {
+      if ((a.shadow ?? 0) !== i) continue;
+      if (a.property === 'shadowBlur') {
+        for (const v of a.values) blur = Math.max(blur, v);
+      } else if (a.property === 'shadowOffset') {
+        for (const [x, y] of a.values) {
+          x0 = Math.min(x0, x);
+          x1 = Math.max(x1, x);
+          y0 = Math.min(y0, y);
+          y1 = Math.max(y1, y);
+        }
+      }
+    }
+    const pad = shadowReach(blur);
+    box = unionRect(box, {
+      x: sh.rect.x + x0 - pad,
+      y: sh.rect.y + y0 - pad,
+      width: sh.rect.width + x1 - x0 + 2 * pad,
+      height: sh.rect.height + y1 - y0 + 2 * pad,
+    });
+  }
+  SHADOW_REACH.set(shadows, { animations, reach: sprite.reach, box });
+  return box;
+}
+
 /**
  * Everywhere `sprite` can draw while its animations run: its reach through
  * its own transform and every transform it is animated through, out to
@@ -291,7 +411,7 @@ function unionRect(a, b) {
  * curve overshoots, offers a `reach` that covers what is between them.
  */
 function extentOf(sprite) {
-  const reach = sprite.reach ?? sprite.rect;
+  const reach = reachOf(sprite);
   const origin = originOf(sprite);
   const m0 = sprite.transform ?? IDENTITY;
   // About its origin, where it can be is the same for a part that only
@@ -347,7 +467,7 @@ function extentOf(sprite) {
  *  that the hole it leaves and the layer meet. */
 function rasterRectOf(sprite) {
   if (sprite.contents != null) return sprite.rect;
-  const reach = sprite.reach ?? sprite.rect;
+  const reach = reachOf(sprite);
   const x = Math.floor(reach.x) - RASTER_PAD;
   const y = Math.floor(reach.y) - RASTER_PAD;
   return {
@@ -404,6 +524,11 @@ export class SpriteLayers {
     this.solid = Boolean(forms?.includes?.('matrix3d'));
     // and a video's frames on a layer need its video surfaces
     this.videos = canLiftVideo(this.native);
+    // and a part that is its shadows, a box masked by a shape: every
+    // bridge that lifts anything has both, but a fake one may not
+    this.shadows =
+      typeof this.native.createShapeLayer === 'function' &&
+      typeof this.native.setShapeProps === 'function';
     this.hosts = new Map(); // element -> Map(key -> state)
     this._warned = new WeakSet();
   }
@@ -479,18 +604,27 @@ export class SpriteLayers {
         let parent = null;
         if (sprite.parent !== undefined) {
           parent = now.get(sprite.parent) ?? null;
-          if (!parent || parent.contents !== null || sprite.contents != null) {
+          if (
+            !parent ||
+            parent.contents !== null ||
+            parent.shadow ||
+            sprite.contents != null
+          ) {
             continue;
           }
         }
         const contents = sprite.contents ?? null;
         // a source this bridge cannot show: the element draws it
         if (contents !== null && !this._canShow(contents)) continue;
+        // shadows this bridge cannot mask: the element draws them
+        const casts = castsOnly(sprite);
+        if (casts && (!this.shadows || parent)) continue;
         const raster = rasterRectOf(sprite);
         // a raster's limit; a source's surface is its own size, whatever
-        // the layer is scaled to
+        // the layer is scaled to, and shadows have none
         if (
           contents === null &&
+          !casts &&
           (raster.width > MAX_SIDE || raster.height > MAX_SIDE)
         ) {
           continue;
@@ -530,7 +664,7 @@ export class SpriteLayers {
         // for a source, and past the budget of raster kept for such parts.
         if (!shown) {
           if (contents !== null) continue;
-          const px = raster.width * raster.height;
+          const px = casts ? 0 : raster.width * raster.height;
           if (hidden + px > HIDDEN_BUDGET) continue;
           hidden += px;
         }
@@ -544,7 +678,8 @@ export class SpriteLayers {
           (Boolean(state.clip) !== Boolean(cut.clip) ||
             Boolean(state.outer) !== Boolean(cut.outer) ||
             state.contents !== contents ||
-            state.parent !== parent)
+            state.parent !== parent ||
+            Boolean(state.shadow) !== casts)
         ) {
           this._drop(state, root);
           state = null;
@@ -558,6 +693,7 @@ export class SpriteLayers {
             contents,
             parent,
             Boolean(cut.outer),
+            casts,
           );
         }
         state.sprite = sprite;
@@ -661,7 +797,15 @@ export class SpriteLayers {
     return isVideoFrames(contents) && this.videos;
   }
 
-  _lift(host, key, clipped, contents = null, parent = null, outered = false) {
+  _lift(
+    host,
+    key,
+    clipped,
+    contents = null,
+    parent = null,
+    outered = false,
+    casts = false,
+  ) {
     const layer = this.native.createLayer();
     // a part cut to a clip is in a box of the clip's size that masks to it,
     // and the box is what stands among the layers above the bitmap — or
@@ -714,6 +858,8 @@ export class SpriteLayers {
       order: null,
       // what shows itself on the layer, for a part with a source
       contents,
+      // the box the casters of a part that is its shadows are in
+      shadow: casts ? this._shadowBox(layer) : null,
       lift:
         contents === null
           ? null
@@ -756,6 +902,7 @@ export class SpriteLayers {
     // source paints nothing: it shows itself.
     if (
       !state.lift &&
+      !state.shadow &&
       (state.painted === UNPAINTED ||
         sprite.version !== state.painted ||
         state.rect?.width !== rect.width ||
@@ -862,6 +1009,8 @@ export class SpriteLayers {
     state.props = next;
     // a source that fills the layer with a layer of its own
     state.lift?.layout?.(next.bounds);
+    // shadows, cast in the layer's coordinates
+    if (state.shadow) this._syncShadows(state, sprite, rect);
     // after the model went out, in the same transaction
     this._syncAnimations(state, sprite);
     // the parts inside it, in the element's order, over its raster
@@ -870,6 +1019,97 @@ export class SpriteLayers {
     }
   }
 
+  /** The box a shadow part's casters are in, on its layer, and the mask
+   *  that shows everything in it but the part's own rect. */
+  _shadowBox(layer) {
+    const box = this.native.createLayer();
+    const mask = this.native.createShapeLayer();
+    this.native.addSublayer(layer, box);
+    this.native.setLayerProps(box, { mask });
+    return { box, mask, casters: [], shape: '', props: [] };
+  }
+
+  /**
+   * A shadow part's casters, as its shadows say, in the layer's points:
+   * each the shadow's shape, rounded, moved left past the layer's edge —
+   * out of the box's mask, which only shows inside the layer — and its
+   * shadow offset back by as much, so the shape itself never shows,
+   * whatever its spread; blurred by a radius half the CSS blur, which is
+   * the deviation of the Gaussian CSS blurs by (calibrated against
+   * `<Html>`'s own: a level apart). The first shadow is on top: added last.
+   */
+  _syncShadows(state, sprite, rect) {
+    const s = this.scale;
+    const sh = state.shadow;
+    const shadows = sprite.shadows;
+    const w = rect.width / s;
+    const h = rect.height / s;
+    // the box, and its mask: all of the layer but the part's rect
+    const hole = sprite.rect;
+    const hw = hole.width / s;
+    const hh = hole.height / s;
+    const hr = Math.min((sprite.rectRadius ?? 0) / s, hw / 2, hh / 2);
+    const shape = [
+      ['rect', 0, 0, w, h],
+      ['roundRect', (hole.x - rect.x) / s, (hole.y - rect.y) / s, hw, hh, hr],
+    ];
+    const key = JSON.stringify(shape);
+    if (sh.shape !== key) {
+      this.native.setLayerProps(sh.box, { frame: [0, 0, w, h] });
+      this.native.setLayerProps(sh.mask, { frame: [0, 0, w, h] });
+      this.native.setShapeProps(sh.mask, {
+        path: shape,
+        fillRule: 'evenodd',
+        fillColor: [0, 0, 0, 1],
+      });
+      sh.shape = key;
+    }
+    // one caster a shadow, the first added last
+    if (sh.casters.length !== shadows.length) {
+      for (const caster of sh.casters) this.native.removeFromSuperlayer(caster);
+      sh.casters = shadows.map(() => this.native.createLayer());
+      for (let i = shadows.length - 1; i >= 0; i--) {
+        this.native.addSublayer(sh.box, sh.casters[i]);
+      }
+      sh.props = [];
+    }
+    for (let i = 0; i < shadows.length; i++) {
+      const shadow = shadows[i];
+      const r = shadow.rect;
+      const cw = r.width / s;
+      const ch = r.height / s;
+      const aside = this._aside(rect, r);
+      const next = {
+        frame: [(r.x - rect.x) / s - aside, (r.y - rect.y) / s, cw, ch],
+        backgroundColor: [0, 0, 0, 1],
+        cornerRadius: Math.min((shadow.radius ?? 0) / s, cw / 2, ch / 2),
+        shadowColor: shadow.color,
+        shadowOpacity: 1,
+        shadowRadius: (shadow.blur ?? 0) / (2 * s),
+        shadowOffset: [aside + (shadow.x ?? 0) / s, (shadow.y ?? 0) / s],
+      };
+      const was = sh.props[i] ?? {};
+      const out = {};
+      let any = false;
+      for (const k of Object.keys(next)) {
+        const v = next[k];
+        if (Array.isArray(v) ? !sameMatrix(was[k], v) : was[k] !== v) {
+          out[k] = v;
+          any = true;
+        }
+      }
+      if (any) this.native.setLayerProps(sh.casters[i], out);
+      sh.props[i] = next;
+    }
+  }
+
+  /** How far, in points, a caster of a shape at `r` in a layer at `rect`
+   *  moves left to be clear of the layer: its right edge a point past the
+   *  layer's left. */
+  _aside(rect, r) {
+    return (r.x + r.width - rect.x) / this.scale + 1;
+  }
+
   _paint(state, sprite, rect) {
     const ctx = state.raster.ensure(
       this.promotion,
@@ -909,7 +1149,7 @@ export class SpriteLayers {
     const listed = (id) => wanted.some((a) => a.id === id);
     for (const [id, run] of state.runs) {
       if (listed(id)) continue;
-      this.native.removeAnimation(state.layer, run.caKey);
+      this.native.removeAnimation(run.layer, run.caKey);
       this._ends().delete(run.caId);
       state.runs.delete(id);
     }
@@ -919,11 +1159,26 @@ export class SpriteLayers {
       if (state.runs.has(a.id) || state.done.has(a.id)) continue;
       const caId = `rxs${++spriteSeq}`;
       const caKey = `sprite:${caId}`;
+      // a shadow's goes on its caster, in the caster's terms
+      let layer = state.layer;
+      let keyPath = a.property;
+      let values = a.values;
+      if (a.property === 'transform') {
+        values = a.values.map((m) => inPoints(m, s));
+      } else if (SHADOW_PROPERTIES.has(a.property)) {
+        const i = a.shadow ?? 0;
+        layer = state.shadow?.casters[i];
+        if (!layer) continue;
+        if (a.property === 'shadowBlur') {
+          keyPath = 'shadowRadius';
+          values = a.values.map((v) => v / (2 * s));
+        } else if (a.property === 'shadowOffset') {
+          const aside = this._aside(state.rect, sprite.shadows[i].rect);
+          values = a.values.map(([x, y]) => [aside + x / s, y / s]);
+        }
+      }
       const opts = {
-        values:
-          a.property === 'transform'
-            ? a.values.map((m) => inPoints(m, s))
-            : a.values,
+        values,
         duration: a.duration / 1000,
         id: caId,
       };
@@ -935,7 +1190,7 @@ export class SpriteLayers {
       // from the frame that asked: ahead, or already that far in
       if (a.delay) opts.delay = a.delay / 1000;
       try {
-        this.native.addAnimation(state.layer, a.property, opts, caKey);
+        this.native.addAnimation(layer, keyPath, opts, caKey);
       } catch (err) {
         this._warn(
           state.host,
@@ -943,7 +1198,7 @@ export class SpriteLayers {
         );
         continue;
       }
-      state.runs.set(a.id, { caId, caKey, held: Boolean(a.hold) });
+      state.runs.set(a.id, { caId, caKey, layer, held: Boolean(a.hold) });
       this._ends().set(caId, (ev) => this._ended(state, a.id, caId, ev));
     }
   }

package/src/node.d.ts

@@ -220,6 +220,24 @@ export interface Context2D {
     dw: number,
     dh: number,
   ): void;
+  /**
+   * Draw an image through a projection, in one draw: its pixel (u, v) lands
+   * where the 3×3 `matrix` — row-major, `[a, b, c, d, e, f, g, h, i]` — takes
+   * it, ((a·u + b·v + c) / w, (d·u + e·v + f) / w) with
+   * w = g·u + h·v + i, and the current transform takes that; clipped and
+   * faded by `globalAlpha` as `drawImage` is. A plane turned out of the page
+   * — CSS `rotateY()` in a `perspective` — is one draw where it would be
+   * hundreds of tiles each drawn through the affine matrix nearest it.
+   * Answers false, drawing nothing, where a corner of the image has w ≤ 0,
+   * behind the viewer.
+   *
+   * The Wayland context only. A GPU interpolates texture coordinates in
+   * perspective; XRender on glamor divides at the corners and folds the
+   * image along its diagonal, and CoreGraphics and Direct2D draw an image
+   * through an affine matrix alone. Test for it with `'drawImageProjected'
+   * in ctx`, and tile where it is absent.
+   */
+  drawImageProjected?(image: unknown, matrix: readonly number[]): boolean;
   createLinearGradient(
     x0: number,
     y0: number,
@@ -281,6 +299,30 @@ export type SpriteMatrix3D = [
  *  0..1, or one of Core Animation's curve names. */
 export type SpriteTiming = [number, number, number, number] | string;
 
+/** A colour as a sprite's shadows take it: straight sRGB, red, green, blue
+ *  and alpha each 0 to 1. */
+export type SpriteColor = [number, number, number, number];
+
+/**
+ * A shadow a part casts, as CSS's outer `box-shadow` casts one: the shape of
+ * `rect` with `radius` corners, `x` and `y` away, blurred by `blur` — CSS's
+ * blur radius, a Gaussian of half of it — in `color`. Device pixels, window
+ * coordinates, untransformed like the part's `rect`. A spread is the
+ * element's to fold into `rect` and `radius`, as CSS spells it out.
+ */
+export interface SpriteShadow {
+  rect: Rect;
+  /** The radius of `rect`'s corners: a circular arc at each of the four. 0
+   * when left out. */
+  radius?: number;
+  /** 0 when left out. */
+  x?: number;
+  y?: number;
+  /** 0 when left out: a hard shadow. */
+  blur?: number;
+  color: SpriteColor;
+}
+
 /**
  * An animation the render server runs on a sprite: keyframes for one
  * property, played as CSS plays an animation's iterations.
@@ -290,11 +332,22 @@ export interface SpriteAnimation {
    * reports. An animation is attached once per id: to change one, give it
    * a new id. */
   id: string;
-  property: 'opacity' | 'transform';
+  /** The layer's opacity or transform, or one of its shadows' blur, colour
+   * or offset (`shadow`). */
+  property:
+    'opacity' | 'transform' | 'shadowBlur' | 'shadowColor' | 'shadowOffset';
+  /** Which of the part's `shadows` a shadow's animation is of; 0 when left
+   * out. */
+  shadow?: number;
   /** At least two: opacities, or matrices for a transform — sampled densely
    * where the element interpolates in a way the render server would not.
-   * A transform's may be `matrix3d`s, in any mix with `matrix`es. */
-  values: number[] | (SpriteMatrix | SpriteMatrix3D)[];
+   * A transform's may be `matrix3d`s, in any mix with `matrix`es. A
+   * shadow's are blurs and `[x, y]` offsets in device pixels, or colours. */
+  values:
+    | number[]
+    | (SpriteMatrix | SpriteMatrix3D)[]
+    | SpriteColor[]
+    | [number, number][];
   /** One per value, 0 to 1, never decreasing; evenly spaced when left out. */
   keyTimes?: number[];
   /** One curve per segment, so one fewer than `values`; linear when left
@@ -356,6 +409,19 @@ export interface Sprite {
    * the current frame itself (docs/extending.md).
    */
   contents?: VideoFrames;
+  /**
+   * What the part casts, the first on top, as CSS lists them: a part with
+   * shadows, and no `paint` or `contents`, is its shadows alone, which the
+   * presenter draws on the GPU — a glow its element would blur a pixel at a
+   * time — and runs their animations. None of them falls inside `rect`,
+   * with `rectRadius` corners, as an outer shadow is never drawn under the
+   * box that casts it; where they reach is worked out from them, through
+   * every keyframe, so `reach` need not say.
+   */
+  shadows?: SpriteShadow[];
+  /** The radius of `rect`'s corners, in device pixels, where its `shadows`
+   * stop. 0 when left out. */
+  rectRadius?: number;
   /** Compared with `===` from frame to frame; a change paints the part
    * again. Left out, it is painted once. */
   version?: unknown;

package/src/nodes/sprites.js

@@ -37,6 +37,12 @@ export class NodeSprites {
    *   milliseconds and `delay` counted from the frame that asks — negative
    *   for one that started before it. An animation is attached once per
    *   `id`: to change one, give it a new id.
+   * - `shadows`, in place of `paint`: a part that is CSS's outer box
+   *   shadows alone, each `{ rect, radius, x, y, blur, color }` in device
+   *   pixels and straight sRGB, the first on top, none falling inside the
+   *   part's `rect` (with `rectRadius` corners); their animations are of
+   *   `shadowBlur`, `shadowColor` and `shadowOffset`, `shadow` saying
+   *   which.
    *
    * Asked every frame, after layout and before the damage is taken, on a
    * window whose presenter lifts sprites; nowhere else. An element whose

package/src/wayland/context2d.js

@@ -65,6 +65,8 @@ const MODE_TEXTURE = 1;
 const MODE_GLYPH = 2;
 const MODE_RRECT = 3;
 const MODE_GRADIENT = 4;
+/** A texture read through a projection: `vParams` is (s/w, t/w, 1/w). */
+const MODE_PROJECTIVE = 5;
 
 /**
  * The stencil buffer, shared between two uses: bit 7 is the clip (set where
@@ -114,7 +116,9 @@ const FRAG = `
 precision mediump float;
 varying vec2 vUV;
 varying vec4 vColor;
-varying vec4 vParams;
+// highp: in MODE_PROJECTIVE these are texture coordinates over w, divided
+// per fragment, and half floats would put a large texture a pixel out
+varying highp vec4 vParams;
 uniform int uMode;
 uniform int uSwizzle;
 uniform sampler2D uTex;
@@ -156,6 +160,10 @@ void main() {
     else if (w < 0.0) a = 1.0 - smoothstep(w, -w, d);
     else a = 1.0 - smoothstep(-0.5, 0.5, d);
     gl_FragColor = vColor * a;
+  } else if (uMode == 5) {
+    // Interpolated across the quad in the plane of the screen, s/w, t/w and
+    // 1/w are each exact, and so is their quotient: a texture in perspective.
+    gl_FragColor = vColor * sampleTex(vParams.xy / vParams.z);
   } else {
     // Gradients are evaluated per fragment from its device position, so any
     // shape — a cover quad over a path included — can be filled with one.
@@ -1450,6 +1458,56 @@ export class WaylandContext2D {
     );
   }
 
+  /**
+   * Draw `img` through a projection, as one quad: its pixel (u, v) lands
+   * where the 3×3 `m` — row-major, `[a, b, c, d, e, f, g, h, i]` — takes it,
+   * ((a·u + b·v + c) / w, (d·u + e·v + f) / w) with w = g·u + h·v + i, and
+   * the current transform takes that. Clipped and faded by `globalAlpha` as
+   * `drawImage` is. Each corner carries its texture coordinates over its w,
+   * which are exact anywhere across the quad, and the fragment divides them
+   * back: the image in perspective, where a quad's own interpolation would
+   * fold it along its diagonal. That fold is what RENDER on glamor draws for
+   * a projective picture transform, and why X11 has no such call.
+   *
+   * Draws nothing and answers false where a corner has w ≤ 0, behind the
+   * viewer: the caller draws the part in front another way.
+   */
+  drawImageProjected(img, m) {
+    this._claim();
+    const src = this._textureFor(img);
+    if (!src) return false;
+    const [a, b, c, d, e, f, g, h, i] = m;
+    const W = src.w;
+    const H = src.h;
+    const ctm = this._m;
+    const pos = new Array(8);
+    const params = new Array(16);
+    const us = [0, W, W, 0];
+    const vs = [0, 0, H, H];
+    for (let k = 0; k < 4; k++) {
+      const u = us[k];
+      const v = vs[k];
+      const w = g * u + h * v + i;
+      if (!(w > 1e-9)) return false;
+      const x = (a * u + b * v + c) / w;
+      const y = (d * u + e * v + f) / w;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+      pos[k * 2] = applyX(ctm, x, y);
+      pos[k * 2 + 1] = applyY(ctm, x, y);
+      const s = u / W;
+      // a render target's row 0 is the bottom of what was drawn into it
+      const t = src.flipY ? 1 - v / H : v / H;
+      params[k * 4] = s / w;
+      params[k * 4 + 1] = t / w;
+      params[k * 4 + 2] = 1 / w;
+      params[k * 4 + 3] = 0;
+    }
+    this._setMode(MODE_PROJECTIVE, src.tex, src.swizzle);
+    const alpha = this.globalAlpha;
+    this._quad(pos, ZERO8, [alpha, alpha, alpha, alpha], params);
+    return true;
+  }
+
   /**
    * Write pixels, ignoring the transform and the clip (the canvas rule).
    * `dirtyX/Y/Width/Height` select part of the data, as the spec has it.
@@ -1926,7 +1984,8 @@ export class WaylandContext2D {
     }
   }
 
-  /** Two triangles from four corners, in order TL, TR, BR, BL. */
+  /** Two triangles from four corners, in order TL, TR, BR, BL. `params` is
+   * one vec4 for every corner, or sixteen numbers, a vec4 a corner. */
   _quad(pos, uv, color, params) {
     // Buffering is taking the device, not a step before it: the quad is GL
     // work that has been decided on and not yet issued, and the handover in
@@ -1935,9 +1994,11 @@ export class WaylandContext2D {
     this._claim();
     if (this._n + 6 > MAX_VERTS) this._flush();
     const v = this._verts;
+    const each = params.length === 16 ? 4 : 0;
     let o = this._n * STRIDE;
     for (let k = 0; k < 6; k++) {
       const i = TRI[k];
+      const p = i * each;
       v[o++] = pos[i * 2];
       v[o++] = pos[i * 2 + 1];
       v[o++] = uv[i * 2];
@@ -1946,10 +2007,10 @@ export class WaylandContext2D {
       v[o++] = color[1];
       v[o++] = color[2];
       v[o++] = color[3];
-      v[o++] = params[0];
-      v[o++] = params[1];
-      v[o++] = params[2];
-      v[o++] = params[3];
+      v[o++] = params[p];
+      v[o++] = params[p + 1];
+      v[o++] = params[p + 2];
+      v[o++] = params[p + 3];
     }
     this._n += 6;
     this.shapeStats.quads++;
@@ -2081,6 +2142,7 @@ export class WaylandContext2D {
 
 const UV_UNIT = Object.freeze([0, 0, 1, 0, 1, 1, 0, 1]);
 const ZERO4 = Object.freeze([0, 0, 0, 0]);
+const ZERO8 = Object.freeze([0, 0, 0, 0, 0, 0, 0, 0]);
 
 // ---- geometry helpers ------------------------------------------------------------
 

package/src/wayland/device.js

@@ -70,7 +70,8 @@ export function releaseDevice(gl) {
  * The owner is the only context that can be holding anything (see above), so
  * flushing it is flushing the device. Call before *reading* a target's pixels
  * behind the contexts' backs — a framebuffer blit, a scroll copy — the way
- * `releaseDevice` is called after writing them.
+ * `releaseDevice` is called after writing them, and before deleting a target
+ * a buffered draw may still read (`WaylandSurface.destroy`).
  */
 export function flushDevice(gl) {
   const device = shared(gl) ? devices.get(gl) : null;

package/src/wayland/surface.js

@@ -25,6 +25,7 @@
 // back by hand either.
 
 import { WaylandContext2D } from './context2d.js';
+import { flushDevice } from './device.js';
 import { GLTarget } from './target.js';
 
 export class WaylandSurface {
@@ -130,6 +131,15 @@ export class WaylandSurface {
     if (this._destroyed) return;
     this._destroyed = true;
     this.app.makeCurrent();
+    // A draw that reads this surface may still be buffered in the context
+    // that made it — a window's quad, to be drawn in one call with the rest
+    // of its batch — and a texture deleted under a draw not yet issued is
+    // sampled as GLES samples a texture that is not there: opaque black. A
+    // surface painted for one paint, drawn, and destroyed in a `finally`
+    // drew as a black box (`<Html>`'s transformed boxes too large to keep).
+    // The owner is the only context holding anything (device.js), so
+    // flushing it issues every draw that could read this one.
+    flushDevice(this.target.gl);
     this._ctx?.destroy();
     this._ctx = null;
     this.target.destroy();