react-x11 2.28.0 → 2.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.28.0",
+  "version": "2.29.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.18.0",
+    "@windowkit/appkit": "^0.19.0",
     "@windowkit/wayland": "^3.1.1",
     "@windowkit/win32": "^0.0.6",
     "dbus-native": "^0.16.0",

package/src/cocoa/promotion.js

@@ -45,6 +45,7 @@ import {
   propBoxProps,
   stylePaintsPlain,
 } from './presenter.js';
+import { SpriteLayers } from './sprites.js';
 
 const ORIGIN = Object.freeze({ x: 0, y: 0 });
 
@@ -61,6 +62,17 @@ const IDLE_GRACE_MS = 1000;
 // the repaint they save (the layer presenter's rule, per raster).
 const MAX_DIRTY_RECTS = 16;
 
+/** Paint order, for entries carrying a `_paintKey`: a key the walk would
+ *  not reach sorts last. */
+function byPaintKey(a, b) {
+  if (!a.key || !b.key) return (a.key ? 1 : 0) - (b.key ? 1 : 0);
+  const n = Math.min(a.key.length, b.key.length);
+  for (let i = 0; i < n; i++) {
+    if (a.key[i] !== b.key[i]) return a.key[i] - b.key[i];
+  }
+  return a.key.length - b.key.length;
+}
+
 const rectsOverlap = (a, b) =>
   a.x < b.x + b.width &&
   b.x < a.x + a.width &&
@@ -243,6 +255,9 @@ export class CocoaPromotion {
       layerOf: (node) => this.promoted.get(node)?.visual.layer ?? null,
       onIdle: (node) => this._idle(node),
     });
+    // the parts of elements' drawing they offer (`Node.sprites()`), each on
+    // a layer of its own under the same rules (src/cocoa/sprites.js)
+    this.sprites = new SpriteLayers(this);
     this._claiming = false;
   }
 
@@ -390,8 +405,19 @@ export class CocoaPromotion {
    */
   frame(root, layoutRan) {
     if (layoutRan) this.layoutGen++;
-    if (this.promoted.size === 0 && this.candidates.size === 0) return;
+    // what elements offer, asked before anything is decided: an answer is
+    // about the element's own drawing, not about the layers
+    const offers = this.sprites.ask(root);
+    if (
+      this.promoted.size === 0 &&
+      this.candidates.size === 0 &&
+      offers.size === 0 &&
+      this.sprites.hosts.size === 0
+    ) {
+      return;
+    }
     const native = this.native;
+    let lifted = null;
     native.txBegin({ disableActions: true });
     try {
       // Later-painted first: a node painted after this one that is coming
@@ -416,13 +442,26 @@ export class CocoaPromotion {
           }
         }
       }
+      // Then the parts, against the layers this frame keeps: a node
+      // promoted over a part is a layer above it, not ink on it.
+      lifted = this.sprites.decide(root, offers);
+      // One order for every layer above the bitmap, nodes and parts alike.
       const order = this._inPaintOrder([...this.promoted.keys()]);
+      for (const state of this.sprites.entries()) {
+        order.push({ state, key: state.order });
+      }
+      order.sort(byPaintKey);
       for (let i = 0; i < order.length; i++) {
-        this._sync(order[i].node, i, root, layoutRan);
+        const { node, state } = order[i];
+        if (node) this._sync(node, i, root, layoutRan);
+        else this.sprites.sync(state, i);
       }
     } finally {
       native.txCommit();
     }
+    // An element told which of its parts are on layers now may claim,
+    // restyle or ask for frames; the frame has not taken its damage yet.
+    if (lifted?.size) this.sprites.notify(lifted);
   }
 
   _mayStay(node, key) {
@@ -528,17 +567,22 @@ export class CocoaPromotion {
 
   _inPaintOrder(nodes) {
     const keyed = nodes.map((node) => ({ node, key: this._paintKey(node) }));
-    keyed.sort((a, b) => {
-      if (!a.key || !b.key) return (a.key ? 1 : 0) - (b.key ? 1 : 0);
-      const n = Math.min(a.key.length, b.key.length);
-      for (let i = 0; i < n; i++) {
-        if (a.key[i] !== b.key[i]) return a.key[i] - b.key[i];
-      }
-      return a.key.length - b.key.length;
-    });
+    keyed.sort(byPaintKey);
     return keyed;
   }
 
+  /**
+   * Where an element offering parts stands in the paint order, or null when
+   * none of them may go on a layer: hidden, inside a `<glarea>`, or itself
+   * faded — its group on the bitmap would leave a part's layer out of it. A
+   * faded ancestor is `_clear`'s to find, as it is for a node.
+   */
+  _spritePlace(host) {
+    if (host.destroyed || host.hidden) return null;
+    if (insideGlArea(host) || fadesAsGroup(host)) return null;
+    return this._paintKey(host);
+  }
+
   /**
    * Is nothing painted over this node, is all of it visible, and is it in
    * no faded group? Walked up the chain: at every level, what the parent
@@ -548,11 +592,11 @@ export class CocoaPromotion {
    * it, and the parent must not fade: its group is drawn on the bitmap or on
    * its own layer, and either way a layer of the node's would be outside it.
    */
-  _clear(node) {
+  _clear(node, bounds = node._subtreeBounds()) {
     // the exact reach, not `paintBounds()`: that one carries the damage
     // model's pixel of slop, and a section laid out flush under a card
-    // would read as reaching into it
-    const bounds = node._subtreeBounds();
+    // would read as reaching into it. An element's part is asked about at
+    // everywhere it can draw (src/cocoa/sprites.js).
     for (let n = node; !n.isWindow; n = n.parent) {
       const parent = n.parent;
       if (!parent) return false;
@@ -733,6 +777,7 @@ export class CocoaPromotion {
 
   /** Everything off the root layer and freed: the window is going. */
   destroy() {
+    this.sprites.destroy();
     for (const timer of this.idle.values()) clearTimeout(timer);
     this.idle.clear();
     this.releasing.clear();

package/src/cocoa/sprites.js

@@ -0,0 +1,562 @@
+// Sprites on the surface presenter (issue #819): the parts of an element's
+// drawing it offers (`Node.sprites()`, src/nodes/sprites.js), each on a
+// CALayer of its own above the window's bitmap, with the animations it
+// carries run by the render server — a CSS animation inside `<Html>`, say,
+// at no JavaScript frame at all.
+//
+// It is layer promotion with an element's part in place of a node, and it
+// is promotion's to run (src/cocoa/promotion.js): the same z-order test,
+// asked of the element at everywhere the part can draw (`_clear`), the same
+// claim of the bitmap under it on the way onto a layer and off it, one order
+// among every layer above the bitmap, and the same rule that declining is
+// always safe — a part the frame refuses is one the element draws itself,
+// as it would anywhere else. What is the element's and nobody else's is its
+// inside: it offers only a part nothing it draws after the part overlaps,
+// and it leaves a hole where a lifted one is (`spritesLifted`).
+//
+// A part's content is a raster the presenter paints by calling the part's
+// own `paint`, at opacity 1 and untransformed, and paints again when its
+// `version` changes; its opacity and its transform are the layer's, and so
+// are its animations, keyframes the bridge hands to Core Animation. A
+// transform is CSS's matrix, which the bridge takes from
+// `@windowkit/appkit` 0.19 (`transformForms()`) along with the negative
+// delay a part joined half way through needs, so that is the bridge sprites
+// ask for: on an older one nothing is asked and every part is drawn by its
+// element.
+
+import { RASTER_PAD, RasterState } from './presenter.js';
+import { DEV } from '../nodes/util.js';
+
+// Past this many device pixels on a side a part is drawn by its element: a
+// layer's contents are a bitmap, and a page-sized one is a page-sized
+// upload for every new version.
+const MAX_SIDE = 8192;
+
+// Sorted after the element's children, which its own drawing comes after
+// (`Node.paint` paints the children first), and before its next sibling.
+const AFTER_CHILDREN = Number.MAX_SAFE_INTEGER;
+
+const IDENTITY = Object.freeze([1, 0, 0, 1, 0, 0]);
+
+// what a part's raster holds before its first paint
+const UNPAINTED = Symbol('unpainted');
+
+// the ids the bridge reports an animation's end under: unique per process,
+// looked up per app (`_animationEnds`), like LayerAnimations'
+let spriteSeq = 0;
+
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+
+const isRect = (r) =>
+  r != null &&
+  finite(r.x) &&
+  finite(r.y) &&
+  finite(r.width) &&
+  finite(r.height) &&
+  r.width > 0 &&
+  r.height > 0;
+
+const isMatrix = (m) => Array.isArray(m) && m.length === 6 && m.every(finite);
+
+const isCurve = (t) =>
+  typeof t === 'string' ||
+  (Array.isArray(t) &&
+    t.length === 4 &&
+    t.every(finite) &&
+    t[0] >= 0 &&
+    t[0] <= 1 &&
+    t[2] >= 0 &&
+    t[2] <= 1);
+
+/** 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;
+  if (!finite(a.duration) || !(a.duration > 0)) return false;
+  const values = a.values;
+  if (!Array.isArray(values) || values.length < 2) return false;
+  const value = a.property === 'opacity' ? finite : isMatrix;
+  if (!values.every(value)) return false;
+  if (a.keyTimes !== undefined) {
+    const t = a.keyTimes;
+    if (!Array.isArray(t) || t.length !== values.length || t[0] !== 0) {
+      return false;
+    }
+    for (let i = 0; i < t.length; i++) {
+      if (!finite(t[i]) || t[i] > 1 || (i > 0 && t[i] < t[i - 1])) {
+        return false;
+      }
+    }
+  }
+  if (a.timings !== undefined) {
+    const t = a.timings;
+    if (!Array.isArray(t) || t.length !== values.length - 1) return false;
+    if (!t.every(isCurve)) return false;
+  }
+  if (a.delay !== undefined && !finite(a.delay)) return false;
+  if (
+    a.repeat !== undefined &&
+    !(a.repeat === Infinity || (finite(a.repeat) && a.repeat > 0))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/** Is `sprite` a part as `Node.sprites()` documents one? */
+function isSprite(sprite) {
+  if (sprite == null || typeof sprite.key !== 'string') return false;
+  if (!isRect(sprite.rect) || typeof sprite.paint !== 'function') return false;
+  if (sprite.reach !== undefined && !isRect(sprite.reach)) return false;
+  if (sprite.opacity !== undefined && !finite(sprite.opacity)) return false;
+  if (sprite.transform !== undefined && !isMatrix(sprite.transform)) {
+    return false;
+  }
+  if (
+    sprite.origin !== undefined &&
+    !(
+      sprite.origin != null &&
+      finite(sprite.origin.x) &&
+      finite(sprite.origin.y)
+    )
+  ) {
+    return false;
+  }
+  const animations = sprite.animations;
+  if (animations !== undefined) {
+    if (!Array.isArray(animations) || !animations.every(isAnimation)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+const originOf = (sprite) =>
+  sprite.origin ?? {
+    x: sprite.rect.x + sprite.rect.width / 2,
+    y: sprite.rect.y + sprite.rect.height / 2,
+  };
+
+/** `rect` through `m` about `origin`: the bounds of its four corners. */
+function mapRect(rect, m, origin) {
+  let x0 = Infinity;
+  let y0 = Infinity;
+  let x1 = -Infinity;
+  let y1 = -Infinity;
+  for (const [px, py] of [
+    [rect.x, rect.y],
+    [rect.x + rect.width, rect.y],
+    [rect.x, rect.y + rect.height],
+    [rect.x + rect.width, rect.y + rect.height],
+  ]) {
+    const dx = px - origin.x;
+    const dy = py - origin.y;
+    const x = m[0] * dx + m[2] * dy + m[4] + origin.x;
+    const y = m[1] * dx + m[3] * dy + m[5] + origin.y;
+    if (x < x0) x0 = x;
+    if (y < y0) y0 = y;
+    if (x > x1) x1 = x;
+    if (y > y1) y1 = y;
+  }
+  return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
+}
+
+function unionRect(a, b) {
+  if (!a) return b;
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y,
+  };
+}
+
+/**
+ * Everywhere `sprite` can draw while its animations run: its reach through
+ * its own transform and every transform it is animated through, out to
+ * whole pixels and the antialiasing a raster is padded for. Between two
+ * keyframes Core Animation interpolates the matrices by their parts, which
+ * stays within a pixel of the two for the densely sampled keyframes a CSS
+ * transform arrives as; an element whose keyframes are far apart, or whose
+ * curve overshoots, offers a `reach` that covers what is between them.
+ */
+function extentOf(sprite) {
+  const reach = sprite.reach ?? sprite.rect;
+  const origin = originOf(sprite);
+  let box = mapRect(reach, sprite.transform ?? IDENTITY, origin);
+  for (const a of sprite.animations ?? []) {
+    if (a.property !== 'transform') continue;
+    for (const m of a.values) box = unionRect(box, mapRect(reach, m, origin));
+  }
+  const x = Math.floor(box.x) - RASTER_PAD;
+  const y = Math.floor(box.y) - RASTER_PAD;
+  return {
+    x,
+    y,
+    width: Math.ceil(box.x + box.width) + RASTER_PAD - x,
+    height: Math.ceil(box.y + box.height) + RASTER_PAD - y,
+  };
+}
+
+/** The raster a part's content is painted into: its reach, out to whole
+ *  pixels and padded for antialiasing, untransformed. */
+function rasterRectOf(sprite) {
+  const reach = sprite.reach ?? sprite.rect;
+  const x = Math.floor(reach.x) - RASTER_PAD;
+  const y = Math.floor(reach.y) - RASTER_PAD;
+  return {
+    x,
+    y,
+    width: Math.ceil(reach.x + reach.width) + RASTER_PAD - x,
+    height: Math.ceil(reach.y + reach.height) + RASTER_PAD - y,
+  };
+}
+
+const sameMatrix = (a, b) =>
+  a === b || (a != null && b != null && a.every((v, i) => v === b[i]));
+
+/**
+ * The lifted parts of every element in one window: a layer each, its raster,
+ * and what the render server runs on it. `CocoaPromotion` asks, decides and
+ * syncs through it inside its own frame.
+ */
+export class SpriteLayers {
+  constructor(promotion) {
+    this.promotion = promotion;
+    this.native = promotion.native;
+    this.scale = promotion.scale;
+    this.app = promotion.app;
+    // a matrix and a negative delay are what a CSS animation needs from the
+    // bridge, and @windowkit/appkit 0.19 is where both are
+    this.supported = Boolean(
+      this.native.transformForms?.()?.includes?.('matrix'),
+    );
+    this.hosts = new Map(); // element -> Map(key -> state)
+    this._warned = new WeakSet();
+  }
+
+  _ends() {
+    return (this.app._animationEnds ??= new Map());
+  }
+
+  _warn(host, message) {
+    if (!DEV || this._warned.has(host)) return;
+    this._warned.add(host);
+    console.warn(`react-x11: <${host.kind}> ${message}`);
+  }
+
+  /**
+   * Every element's answer this frame, before anything is decided: the
+   * elements that offer a part, and what they offer. An element that throws
+   * offers nothing and draws everything, which is what it would do anywhere
+   * else.
+   */
+  ask(root) {
+    const offers = new Map();
+    if (!this.supported) return offers;
+    for (const host of root._spriteNodes ?? []) {
+      if (host.destroyed) continue;
+      let list = null;
+      try {
+        list = host.sprites();
+      } catch (err) {
+        this._warn(
+          host,
+          `sprites() threw, and its parts are drawn by it: ${err?.message ?? err}`,
+        );
+      }
+      if (Array.isArray(list) && list.length !== 0) offers.set(host, list);
+    }
+    return offers;
+  }
+
+  /**
+   * Which offered parts go on layers this frame, against the scene as laid
+   * out and the layers promotion has decided on: a part is lifted, kept, or
+   * given back. Answers the elements whose set of lifted parts changed.
+   */
+  decide(root, offers) {
+    const changed = new Set();
+    for (const [host, lifted] of this.hosts) {
+      if (offers.has(host)) continue;
+      for (const state of lifted.values()) this._drop(state, root);
+      this.hosts.delete(host);
+      if (!host.destroyed) changed.add(host);
+    }
+    for (const [host, list] of offers) {
+      const was = this.hosts.get(host);
+      const now = new Map();
+      // where the element stands in the paint order, or null where none of
+      // it may go on a layer: hidden, faded, inside a <glarea>
+      const place = this.promotion._spritePlace(host);
+      for (let index = 0; place && index < list.length; index++) {
+        const sprite = list[index];
+        if (!isSprite(sprite)) {
+          this._warn(
+            host,
+            `offered a sprite that is not one (${JSON.stringify(sprite?.key)}); see Node.sprites()`,
+          );
+          continue;
+        }
+        if (now.has(sprite.key)) continue;
+        const raster = rasterRectOf(sprite);
+        if (raster.width > MAX_SIDE || raster.height > MAX_SIDE) continue;
+        const extent = extentOf(sprite);
+        if (!this.promotion._clear(host, extent)) continue;
+        let state = was?.get(sprite.key);
+        const lifting = !state;
+        if (lifting) state = this._lift(host, sprite.key);
+        state.sprite = sprite;
+        state.order = [...place, AFTER_CHILDREN, index];
+        // the bitmap under where it can be repaints without it, from this
+        // frame on; where it went since, it is the element's own claims
+        // that move the hole
+        if (lifting) this.promotion._claim(root, extent);
+        state.extent = extent;
+        now.set(sprite.key, state);
+      }
+      if (was) {
+        for (const [key, state] of was) {
+          if (!now.has(key)) this._drop(state, root);
+        }
+      }
+      if (now.size !== 0) this.hosts.set(host, now);
+      else this.hosts.delete(host);
+      const before = was?.size ?? 0;
+      if (before !== now.size || [...now.keys()].some((k) => !was.has(k))) {
+        changed.add(host);
+      }
+    }
+    return changed;
+  }
+
+  /** Every lifted part, with its place in the paint order. */
+  entries() {
+    const out = [];
+    for (const lifted of this.hosts.values()) {
+      for (const state of lifted.values()) out.push(state);
+    }
+    return out;
+  }
+
+  /** Tell each element that changed which of its parts are lifted now —
+   *  after the decisions, before the frame paints. */
+  notify(changed) {
+    for (const host of changed) {
+      if (host.destroyed) continue;
+      const keys = new Set(this.hosts.get(host)?.keys() ?? []);
+      try {
+        host.spritesLifted(keys);
+      } catch (err) {
+        this._warn(host, `spritesLifted() threw: ${err?.message ?? err}`);
+      }
+    }
+  }
+
+  _lift(host, key) {
+    const layer = this.native.createLayer();
+    this.native.addSublayer(this.promotion.rootVisual.layer, layer);
+    return {
+      host,
+      key,
+      layer,
+      raster: new RasterState(),
+      painted: UNPAINTED,
+      rect: null, // the raster's rect, device pixels, window coordinates
+      phase: null, // where in a pixel its reach starts
+      props: {},
+      runs: new Map(), // element's animation id -> { caId, caKey, held }
+      // ids the render server is done with, while the element still lists
+      // them: an animation is attached once per id, and an end the element
+      // has not caught up with must not start it again
+      done: new Set(),
+      sprite: null,
+      extent: null,
+      order: null,
+    };
+  }
+
+  /** Off its layer: the layer and its raster go, its animations are
+   *  forgotten, and the bitmap under where it could be repaints with the
+   *  element drawing it again. */
+  _drop(state, root) {
+    this.native.removeFromSuperlayer(state.layer);
+    state.raster.release(this.native);
+    for (const run of state.runs.values()) this._ends().delete(run.caId);
+    state.runs.clear();
+    if (!state.host.destroyed && state.extent) {
+      this.promotion._claim(root, state.extent);
+    }
+  }
+
+  /** The layer as the part says, at `z` among the layers above the bitmap. */
+  sync(state, z) {
+    const sprite = state.sprite;
+    const s = this.scale;
+    const rect = rasterRectOf(sprite);
+    const reach = sprite.reach ?? sprite.rect;
+    const phase = `${reach.x - Math.floor(reach.x)},${reach.y - Math.floor(reach.y)}`;
+    // painted again for a new version, and for a raster of another size or
+    // with the part at another fraction of a pixel; a move by whole pixels
+    // is the layer's alone
+    if (
+      state.painted === UNPAINTED ||
+      sprite.version !== state.painted ||
+      state.rect?.width !== rect.width ||
+      state.rect?.height !== rect.height ||
+      state.phase !== phase
+    ) {
+      this._paint(state, sprite, rect);
+      state.phase = phase;
+    }
+    state.rect = rect;
+    const origin = originOf(sprite);
+    const m = sprite.transform ?? IDENTITY;
+    const next = {
+      bounds: [0, 0, rect.width / s, rect.height / s],
+      anchorPoint: [
+        (origin.x - rect.x) / rect.width,
+        (origin.y - rect.y) / rect.height,
+      ],
+      position: [origin.x / s, origin.y / s],
+      zPosition: z,
+      opacity: Math.min(1, Math.max(0, sprite.opacity ?? 1)),
+      matrix: m,
+    };
+    const prev = state.props;
+    const out = {};
+    let any = false;
+    for (const key of ['bounds', 'anchorPoint', 'position']) {
+      if (!sameMatrix(prev[key], next[key])) {
+        out[key] = next[key];
+        any = true;
+      }
+    }
+    for (const key of ['zPosition', 'opacity']) {
+      if (prev[key] !== next[key]) {
+        out[key] = next[key];
+        any = true;
+      }
+    }
+    if (!sameMatrix(prev.matrix, m)) {
+      out.transform = { matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s] };
+      any = true;
+    }
+    if (any) this.native.setLayerProps(state.layer, out);
+    state.props = next;
+    // after the model went out, in the same transaction
+    this._syncAnimations(state, sprite);
+  }
+
+  _paint(state, sprite, rect) {
+    const ctx = state.raster.ensure(
+      this.promotion,
+      rect.width,
+      rect.height,
+      this.scale,
+    );
+    const root = state.host.root;
+    ctx.save();
+    try {
+      ctx.clearRect(0, 0, rect.width, rect.height);
+      ctx.translate(-rect.x, -rect.y);
+      // a part paints whole: there is no pass to cull it by
+      if (root) root._paintDamage = null;
+      sprite.paint(ctx);
+    } catch (err) {
+      this._warn(
+        state.host,
+        `a sprite's paint() threw: ${err?.message ?? err}`,
+      );
+    } finally {
+      ctx.restore();
+    }
+    this.native.surfaceToLayer(state.raster.surface, state.layer);
+    state.painted = sprite.version;
+  }
+
+  /** What runs on the layer, by the element's ids: one gone from the part
+   *  comes off, one new to it goes on, and one already on is left alone —
+   *  its `delay` is counted from the frame that asks, so it moves every
+   *  frame and means nothing past the first. */
+  _syncAnimations(state, sprite) {
+    const wanted = sprite.animations ?? [];
+    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._ends().delete(run.caId);
+      state.runs.delete(id);
+    }
+    for (const id of state.done) if (!listed(id)) state.done.delete(id);
+    const s = this.scale;
+    for (const a of wanted) {
+      if (state.runs.has(a.id) || state.done.has(a.id)) continue;
+      const caId = `rxs${++spriteSeq}`;
+      const caKey = `sprite:${caId}`;
+      const opts = {
+        values:
+          a.property === 'transform'
+            ? a.values.map((m) => ({
+                matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s],
+              }))
+            : a.values,
+        duration: a.duration / 1000,
+        id: caId,
+      };
+      if (a.keyTimes) opts.keyTimes = a.keyTimes;
+      if (a.timings) opts.timings = a.timings;
+      if (a.repeat !== undefined) opts.repeat = a.repeat;
+      if (a.autoreverse) opts.autoreverse = true;
+      if (a.hold) opts.hold = true;
+      // 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);
+      } catch (err) {
+        this._warn(
+          state.host,
+          `the bridge refused sprite animation ${JSON.stringify(a.id)}: ${err?.message ?? err}`,
+        );
+        continue;
+      }
+      state.runs.set(a.id, { caId, caKey, held: Boolean(a.hold) });
+      this._ends().set(caId, (ev) => this._ended(state, a.id, caId, ev));
+    }
+  }
+
+  /** The bridge's `animation-end` for one of ours. A held one stays on the
+   *  layer, showing its last value, until the element stops listing it. */
+  _ended(state, id, caId, ev) {
+    this._ends().delete(caId);
+    const run = state.runs.get(id);
+    if (run?.caId === caId) {
+      state.done.add(id);
+      if (!run.held) state.runs.delete(id);
+    }
+    if (state.host.destroyed) return;
+    try {
+      state.host.spriteAnimationEnded(state.key, id, ev?.finished !== false);
+    } catch (err) {
+      this._warn(
+        state.host,
+        `spriteAnimationEnded() threw: ${err?.message ?? err}`,
+      );
+    }
+  }
+
+  /** Everything off the root and freed: the window is going. */
+  destroy() {
+    for (const lifted of this.hosts.values()) {
+      for (const state of lifted.values()) {
+        this.native.removeFromSuperlayer(state.layer);
+        state.raster.release(this.native);
+        for (const run of state.runs.values()) this._ends().delete(run.caId);
+      }
+    }
+    this.hosts.clear();
+  }
+}

package/src/cocoa/window.js

@@ -260,6 +260,10 @@ export class CocoaWindow {
         this._promotion.noteInvalidate(damage, layoutChanged);
       this.prepareFrame = (root, layoutRan) =>
         this._promotion.frame(root, layoutRan);
+      // An element's parts on layers of their own (src/cocoa/sprites.js)
+      // are asked for in that frame, so an element whose parts changed with
+      // nothing else to paint asks for one.
+      this.spritesChanged = () => this._reactX11Node?._scheduleFrame();
     }
     app._registerWindow(this);
   }

package/src/node.d.ts

@@ -230,6 +230,75 @@ export interface PaintCachePlan {
   tint?: string;
 }
 
+/**
+ * CSS's `matrix(a, b, c, d, e, f)`: a point (x, y) goes to
+ * (a·x + c·y + e, b·x + d·y + f), with `e` and `f` in device pixels.
+ */
+export type SpriteMatrix = [number, number, number, number, number, number];
+
+/** A cubic-bezier's control points `[x1, y1, x2, y2]`, `x1` and `x2` in
+ *  0..1, or one of Core Animation's curve names. */
+export type SpriteTiming = [number, number, number, number] | string;
+
+/**
+ * An animation the render server runs on a sprite: keyframes for one
+ * property, played as CSS plays an animation's iterations.
+ */
+export interface SpriteAnimation {
+  /** The element's own name for this run, which `spriteAnimationEnded`
+   * reports. An animation is attached once per id: to change one, give it
+   * a new id. */
+  id: string;
+  property: 'opacity' | 'transform';
+  /** At least two: opacities, or matrices for a transform — sampled densely
+   * where the element interpolates in a way the render server would not. */
+  values: number[] | SpriteMatrix[];
+  /** 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
+   * out. */
+  timings?: SpriteTiming[];
+  /** Milliseconds, one iteration. */
+  duration: number;
+  /** Milliseconds from the frame that asks: ahead, or — negative — already
+   * that far in. Read when the animation is attached and not after. */
+  delay?: number;
+  /** Iterations, `Infinity` for a loop; one when left out. */
+  repeat?: number;
+  /** Each iteration turns round at its end, as `alternate` does. */
+  autoreverse?: boolean;
+  /** The last value stays on screen after the end. */
+  hold?: boolean;
+}
+
+/**
+ * A part of an element's drawing a presenter may put on a layer of its own
+ * — what `sprites()` answers with (docs/extending.md "Parts of your drawing
+ * on layers of their own").
+ */
+export interface Sprite {
+  /** The same across frames for the same part. */
+  key: string;
+  /** Its box, untransformed: device pixels, window coordinates, like
+   * `abs`. */
+  rect: Rect;
+  /** What it draws, untransformed, when that is more than `rect`. */
+  reach?: Rect;
+  /** Draws the part where it is in the window, as `paint` would, but at
+   * opacity 1 and untransformed. */
+  paint(ctx: Context2D): void;
+  /** Compared with `===` from frame to frame; a change paints the part
+   * again. Left out, it is painted once. */
+  version?: unknown;
+  /** What the layer shows when no animation runs on it; 1 when left out. */
+  opacity?: number;
+  /** …and the transform, about `origin`; the identity when left out. */
+  transform?: SpriteMatrix;
+  /** Device pixels, window coordinates; `rect`'s centre when left out. */
+  origin?: { x: number; y: number };
+  animations?: SpriteAnimation[];
+}
+
 /** How an axis is bounded when layout asks an element for its size.
  * `'exactly'` — the style decided this axis; `'at-most'` — that many pixels
  * are on offer; `'unconstrained'` — nothing bounds it. */
@@ -570,6 +639,28 @@ export declare class Node {
    * read-only.
    */
   paintDamage(): Rect | null;
+  /**
+   * The parts of this element's drawing a presenter may put on layers of
+   * their own, and animate there in the render server — or null, the
+   * default. Asked every frame, after layout and before the damage is
+   * taken, by the macOS surface presenter's layer promotion and by nothing
+   * else: on X11, on Wayland and wherever a frame's scene refuses a part,
+   * the element draws everything, as it would without this.
+   */
+  sprites(): Sprite[] | null;
+  /**
+   * The keys of this element's sprites that are on layers of their own now.
+   * Called in the frame that changes the set, before it paints; `paint`
+   * leaves a lifted part out from then on, and draws again one the set no
+   * longer holds.
+   */
+  spritesLifted(keys: ReadonlySet<string>): void;
+  /** The render server is done with animation `id` on sprite `key`: it ran
+   * out (`finished`), or it was taken off with its layer. */
+  spriteAnimationEnded(key: string, id: string, finished: boolean): void;
+  /** Ask for the frame in which `sprites()` is asked again, when the parts
+   * changed and nothing the element draws did. A no-op where nothing asks. */
+  spritesChanged(): void;
   /**
    * "The pixels in `rect` moved by (dx, dy); the rest of it is new" — for an
    * element with a viewport of its own, whose pan is a scroll in every way

package/src/nodes/node.js

@@ -45,6 +45,7 @@ import { NodePosition } from './position.js';
 import { NodeQueries } from './queries.js';
 import { NodeScrollBlit } from './scrollblit.js';
 import { NodeSelectable } from './selectable.js';
+import { NodeSprites } from './sprites.js';
 import { NodeStyling } from './styling.js';
 import { DEV } from './util.js';
 
@@ -608,6 +609,7 @@ export class Node {
     this.root?._animating.delete(this);
     this.root?._opaqueNodes?.delete(this);
     this.root?._viewportFixedNodes?.delete(this);
+    this.root?._spriteNodes?.delete(this);
     // a surface that goes away takes its selection with it, and the app-wide
     // claim on being the one showing one goes with it too
     this._textSelection?.destroy();
@@ -627,14 +629,18 @@ export class Node {
       root?._layoutHosts?.add(this);
     }
     // an element answering `opaqueRect()` is one the window asks per pass,
-    // and one answering `viewportFixedRects()` one it asks per scroll blit
+    // one answering `viewportFixedRects()` one it asks per scroll blit, and
+    // one answering `sprites()` one its presenter asks per frame
     const opaque = this.opaqueRect !== Node.prototype.opaqueRect;
     const fixed = this.viewportFixedRects !== Node.prototype.viewportFixedRects;
+    const sprites = this.sprites !== Node.prototype.sprites;
     if (opaque) this.root?._opaqueNodes?.delete(this);
     if (fixed) this.root?._viewportFixedNodes?.delete(this);
+    if (sprites) this.root?._spriteNodes?.delete(this);
     this.root = root;
     if (opaque) root?._opaqueNodes?.add(this);
     if (fixed) root?._viewportFixedNodes?.add(this);
+    if (sprites) root?._spriteNodes?.add(this);
     // styled before it had a window, so this is where a placed node is
     // first registered (WindowNode._placeNodes)
     if (this.style && isPlaced(this.style)) root?._placedNodes?.add(this);
@@ -1034,4 +1040,5 @@ installMethods(
   NodePaint,
   NodeBoxPaint,
   NodeSelectable,
+  NodeSprites,
 );

package/src/nodes/sprites.js

@@ -0,0 +1,73 @@
+// Sprites (issue #819): the parts of what an element draws that a retained
+// presenter may lift onto layers of their own, and animate there in the
+// render server. The element's half of the seam is here; the presenter's is
+// src/cocoa/sprites.js, under layer promotion.
+//
+// It is the shape of `opaqueRect()`: an accessor core asks every frame, a
+// registry of the nodes that override it (`WindowNode._spriteNodes`, kept by
+// `_setRoot`), and a default that answers nothing, so an element that never
+// heard of sprites pays nothing and one that answers them draws exactly what
+// it draws today wherever nothing asks — on X11, on Wayland, on the layer
+// presenter, and in any frame whose scene refuses a lift.
+
+/** Node's half of sprites, installed onto `Node.prototype` by node.js. */
+export class NodeSprites {
+  /**
+   * The parts of this element's drawing a presenter may put on layers of
+   * their own, or null, the default. Each is a plain object:
+   *
+   * - `key`: a string, the same across frames for the same part.
+   * - `rect`: its box, untransformed — device pixels, window coordinates,
+   *   like `abs`.
+   * - `reach`: what it draws, untransformed, when that is more than `rect`.
+   * - `paint(ctx)`: draws it where it is in the window, as `paint` would,
+   *   but at opacity 1 and untransformed: the layer carries both.
+   * - `version`: compared with `===` from frame to frame; a change paints
+   *   the part again. Left out, it is painted once.
+   * - `opacity`, and `transform` — CSS's `matrix(a, b, c, d, e, f)` as an
+   *   array, `e` and `f` in device pixels — about `origin`, a point in
+   *   device pixels that defaults to `rect`'s centre: the values the layer
+   *   shows when no animation is running on it.
+   * - `animations`: what the render server runs on it, each `{ id,
+   *   property: 'opacity' | 'transform', values, keyTimes, timings,
+   *   duration, delay, repeat, autoreverse, hold }`, with times in
+   *   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.
+   *
+   * Asked every frame, after layout and before the damage is taken, on a
+   * window whose presenter lifts sprites; nowhere else. An element whose
+   * parts changed while nothing was going to paint asks for that frame with
+   * `spritesChanged()`.
+   */
+  sprites() {
+    return null;
+  }
+
+  /**
+   * The keys of this element's sprites that are on layers of their own now,
+   * a set the element may keep. Called in the frame that changes it, before
+   * that frame paints. From then on `paint` must not draw a lifted part —
+   * where it is, the window's bitmap holds a hole the layer shows through —
+   * and must draw again one the set no longer holds: a presenter gives a
+   * part back whenever the scene stops allowing it, and the bitmap under it
+   * is repainted in that same frame.
+   */
+  spritesLifted(keys) {}
+
+  /**
+   * The render server is done with animation `id` on sprite `key`: it ran
+   * out (`finished`), or it was taken off with its layer. Called from the
+   * backend's event, between frames.
+   */
+  spriteAnimationEnded(key, id, finished) {}
+
+  /**
+   * Ask for the frame in which this element's sprites are asked for again —
+   * one whose parts changed while nothing it drew had. Does nothing on a
+   * window whose presenter lifts none.
+   */
+  spritesChanged() {
+    this.root?.window?.spritesChanged?.(this);
+  }
+}

package/src/nodes/window/window.js

@@ -196,6 +196,9 @@ export class WindowNode extends Scrollable(Node) {
     // the nodes answering `viewportFixedRects()`, whose rects a scroll pane
     // they are in repairs when it blits (`_viewportFixedPins`)
     this._viewportFixedNodes = new Set();
+    // the nodes answering `sprites()`, which a presenter that lifts parts of
+    // an element onto layers asks every frame (src/cocoa/sprites.js)
+    this._spriteNodes = new Set();
     // Nodes that want the `attention` event (ntk#37) — an
     // `unstable_onAttention` prop,
     // an `:attention` block, or both. Built before the EventManager so the