react-x11 2.41.0 → 2.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -104,14 +104,14 @@
     "ical.js": "^2.2.1",
     "image-in-browser": "^3.6.0",
     "linebreak": "^1.1.0",
-    "ntk": "^8.17.8",
+    "ntk": "^8.23.0",
     "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
     "@windowkit/appkit": "^0.25.0",
     "@windowkit/wayland": "^3.1.1",
-    "@windowkit/win32": "^0.0.7",
+    "@windowkit/win32": "^0.0.9",
     "dbus-native": "^0.16.0",
     "x11-dri": "^0.9.0"
   },

package/src/cocoa/panehost.js

@@ -31,6 +31,19 @@ const ASKED_KEPT = 16;
  *  drag itself. */
 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 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 {
@@ -45,59 +58,126 @@ 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;
+    this._late = 0;
   }
 
   /**
-   * 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
+   * it has painted the last, so the sizes a drag passes through while a
+   * frame is being painted are never sent, and never answered: a size
+   * 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 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';
-    // a size asked longer ago than the budget, and no frame of it yet
+    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() - oldest.at > budget) this._behind = true;
-    return this._behind ? 'resize' : 'topLeft';
+    if (oldest && now() - Math.max(oldest.at, this._answeredAt) > budget) {
+      this._behind = true;
+    }
+    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;
@@ -106,20 +186,35 @@ class PaneLayer {
     return { contentsScale: scale };
   }
 
-  /** A frame of `width` by `height` device px landed: what it answers of
-   *  the sizes asked, and how long it took. */
+  /**
+   * A frame of `width` by `height` device px landed: what it answers of
+   * the sizes asked, and how long it took. Two frames in a row later than
+   * 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
+   * shown at its size by turns.
+   */
   _answered(width, height) {
     const asked = this._asked;
     // the pane rounds the logical size it was sent back to device pixels
     const slack = Math.max(2, this.wnd.scale ?? 1);
-    const at = asked.findIndex(
+    // the last time it was asked: a drag back and forth asks a size twice
+    const at = asked.findLastIndex(
       (a) =>
         Math.abs(a.width - width) <= slack &&
         Math.abs(a.height - height) <= slack,
     );
     if (at < 0) return;
-    this._behind =
-      now() - asked[at].at > (this.app._resizeWait ?? RESIZE_WAIT_MS);
+    const budget = this.app._resizeWait ?? RESIZE_WAIT_MS;
+    const took = now() - asked[at].at;
+    this._answeredAt = now();
+    if (took > budget) {
+      this._late += 1;
+      if (this._late >= 2) this._behind = true;
+    } else {
+      this._late = 0;
+      if (took <= budget * KEPT_UP) this._behind = false;
+    }
     asked.splice(0, at + 1);
   }
 
@@ -144,6 +239,7 @@ class PaneLayer {
       if (at - (this._askedAt ?? -Infinity) >= GESTURE_GAP_MS) {
         this._asked = [];
         this._behind = false;
+        this._late = 0;
       }
       this._askedAt = at;
       if (this._asked.length === ASKED_KEPT) this._asked.shift();
@@ -161,7 +257,7 @@ class PaneLayer {
         zPosition: 1e7,
         hidden: false,
         ...this._scaleProps(),
-        ...this._gravityProps(),
+        ...this._edgeProps(),
       });
     } finally {
       native.txCommit();
@@ -189,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

@@ -281,6 +281,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 +314,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 +391,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/offscreen.js

@@ -5,13 +5,14 @@
 // An app that makes its own surfaces answers `createSurface(options)` — the
 // Cocoa app over a CG bitmap (src/cocoa/surface.js), the Windows app over a
 // Direct2D bitmap, the Wayland app over a GL render target
-// (src/wayland/surface.js) — and an X connection has no such method and gets
-// ntk's pixmap, from ntk's root, which only an X connection loads
-// (src/ntkroot.js). 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`.
+// (src/wayland/surface.js), and ntk's own app over an X connection with its
+// pixmap (ntk >= 8.21). An app without the method — an older ntk deduped
+// into the tree — gets that pixmap from ntk's root, which only an X
+// connection loads (src/ntkroot.js). 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,

package/src/win32/fonts.js

@@ -407,20 +407,68 @@ class Win32TextLayout {
    * where CoreText cannot and the Cocoa engine breaks at `linebreak`'s
    * opportunities itself. */
   get minWidth() {
+    // asked of the bridge the first time, where it left it out of the
+    // metrics: the line breaker over the whole text again, which a layout
+    // made to be drawn is never asked for
+    if (this._metrics.minWidth === undefined) {
+      this._metrics.minWidth =
+        this._handle != null && this._native.layoutMinWidth
+          ? (this._native.layoutMinWidth(this._handle) ?? 0)
+          : 0;
+    }
     return this._metrics.minWidth;
   }
 
+  /**
+   * Keep the first `cap` lines of what was laid out: they are all this
+   * layout reports, answers for and draws (`_keptEnd`, `_keptHeight`). A
+   * capped paragraph is laid out past its cap to find where the cap falls,
+   * and keeping that layout's first lines is the same picture as laying the
+   * kept text out again, for one native layout where it took two.
+   */
+  _keep(cap) {
+    const lines = this._metrics.lines.slice(0, cap);
+    const last = lines[lines.length - 1];
+    if (!last) return;
+    let width = 0;
+    for (const line of lines)
+      width = Math.max(width, Math.ceil(line.width - 1e-3));
+    this._metrics = {
+      ...this._metrics,
+      lines,
+      width,
+      height: Math.ceil(last.y + last.height),
+      minWidth: undefined,
+    };
+    this._keptEnd = last.end;
+    this._keptHeight = last.y + last.height;
+  }
+
   draw(ctx, x, y) {
+    if (this._keptHeight === undefined) {
+      ctx._drawLayout(this, x, y);
+      return;
+    }
+    // the lines past the cap are in the layout, and stay out of the picture
+    ctx.save();
+    ctx.beginPath();
+    ctx.rect(x - 1e4, y, 2e4 + this._metrics.width, this._keptHeight);
+    ctx.clip();
     ctx._drawLayout(this, x, y);
+    ctx.restore();
   }
 
   indexAt(x, y) {
     const unit = this._native.layoutIndexAt(this._handle, x, y);
-    return this._cpOf(unit);
+    return this._cpOf(Math.min(unit, this._keptEnd ?? unit));
   }
 
   caretPosition(cp) {
-    return this._native.layoutCaret(this._handle, this._cuOf(cp));
+    const unit = this._cuOf(cp);
+    return this._native.layoutCaret(
+      this._handle,
+      Math.min(unit, this._keptEnd ?? unit),
+    );
   }
 
   /**
@@ -567,6 +615,20 @@ export class Win32FontManager {
     // family|weight|italic|size -> the bridge's handle, or null when there is
     // no such face
     this._handles = new Map();
+    // what this bridge's layouts take, asked once (`textFeatures`, from
+    // @windowkit/win32 0.0.9): an older one answers nothing and takes neither
+    this._features = native.textFeatures?.() ?? {};
+  }
+
+  /**
+   * Which of ntk's `justify` modes `layout` takes. DirectWrite justifies
+   * every line but a paragraph's last, which is `justify: true`, and has no
+   * way to justify a last line: `'rest'` says so, and a caller justifies the
+   * other two itself. <Html>, which spaced every justified line through
+   * letter spacing on this engine, lays a justified paragraph out once.
+   */
+  get justifies() {
+    return this._features.justify === true ? 'rest' : false;
   }
 
   /**
@@ -759,7 +821,9 @@ export class Win32FontManager {
       return this._laidOut(sources, base, { ...options, maxWidth: least });
     }
     let laid = sources;
-    let layout = this._laidOut(laid, base, options);
+    let layout =
+      this._prefixLaidOut(sources, base, options, cap) ??
+      this._laidOut(laid, base, options);
     // With no width the bridge lays a paragraph out in a box a million
     // pixels wide, and aligns it there: a centred line's `x` was half a
     // million, an RTL one's a million, and <Html> measured a centred
@@ -776,7 +840,11 @@ export class Win32FontManager {
       layout = this._laidOut(laid, base, { ...options, maxWidth: widest });
     }
     layout.truncated = layout.lines.length > cap;
-    if (layout.truncated) {
+    if (layout.truncated && !elides) {
+      // what was laid out, a prefix or the whole, keeps its first lines
+      laid = spansTo(sources, layout._text.length);
+      layout._keep(cap);
+    } else if (layout.truncated) {
       const last = layout.lines[cap - 1];
       const text = layout._text;
       layout.destroy();
@@ -800,6 +868,43 @@ export class Win32FontManager {
     return layout;
   }
 
+  /**
+   * A capped paragraph laid out only as far as the cap needs: a prefix of
+   * its text that breaks into more lines than `cap`, or null where the
+   * whole text is no longer than a prefix would be. The first lines of a
+   * prefix are the whole text's first lines wherever it reaches past them —
+   * a line's break waits only on the word after it, which then starts a
+   * line of the prefix — and the prefix ends at a break, its last word
+   * whole. <Html> lays a paragraph beside a float out a line at a time,
+   * each `maxLines: 1` over the rest of the paragraph; laid out whole, each
+   * line cost the whole rest of it, twice, and a paragraph cost the square
+   * of its length.
+   */
+  _prefixLaidOut(sources, base, options, cap) {
+    const { maxWidth } = options;
+    if (!(cap < Infinity) || !(maxWidth > 0) || !Number.isFinite(maxWidth)) {
+      return null;
+    }
+    const text = sources.map((span) => String(span.text)).join('');
+    let size = Infinity;
+    for (const span of sources)
+      size = Math.min(size, sizeOf(span.size ?? base.size));
+    // a third of an em a character is narrower than nearly any text is set
+    // in, so a prefix that long nearly always reaches past the lines wanted;
+    // where it does not, one twice as long is tried
+    let take = Math.ceil(maxWidth / (Math.max(1, size) * 0.3)) * cap + 16;
+    while (take < text.length) {
+      let end = take;
+      while (end < text.length && !BREAKING_SPACE.test(text[end])) end++;
+      if (end >= text.length) return null;
+      const layout = this._laidOut(spansTo(sources, end), base, options);
+      if (layout.lines.length > cap) return layout;
+      layout.destroy();
+      take *= 2;
+    }
+    return null;
+  }
+
   /**
    * Where the last line kept of an eliding paragraph ends: as far into
    * `[start, end)` as fits beside the mark in `maxWidth`, white space before
@@ -899,11 +1004,17 @@ export class Win32FontManager {
         align: options.align,
         lineHeight: options.lineHeight,
         rtl: options.direction === 'rtl',
+        // the one mode DirectWrite has (`justifies`); 'last' and 'all' are
+        // the caller's
+        justify: options.justify === true || undefined,
       },
       ranges,
     );
 
-    const raw = this._native.layoutMetrics(handle);
+    const raw = this._native.layoutMetrics(
+      handle,
+      this._features.lazyMinWidth ? { minWidth: false } : undefined,
+    );
     if (DEBUG) {
       // The family is in here because the one way this goes quietly wrong is
       // `resolveStack` not recognising a name and answering `sans-serif`: the