react-x11 2.37.0 → 2.39.0

package/package.json

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

package/src/cocoa/app.js

@@ -39,6 +39,7 @@ import { CocoaColorSampler } from './screencolor.js';
 import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
 import { releaseImageUpload } from '../backend/context2d.js';
+import { PanePlayer, canShowPanePlayers } from './paneplayer.js';
 import { CocoaPlayer, canPlay } from './player.js';
 import { CocoaSurface } from './surface.js';
 import { CocoaSymbols } from './symbols.js';
@@ -224,8 +225,17 @@ export class CocoaApp {
     // what `useSupports('mediaPlayback')` and `<video src>` ask
     // (src/mediaplayback.js), so an app over an older bridge, or a test's
     // fake without them, refuses `src` the way X11 does.
+    //
+    // A `<Frame>` pane plays nothing itself. It runs no NSApplication, so
+    // nothing pumps the bridge's events there: AVFoundation opened the item
+    // and its `player-*` events never arrived, and a page's video sat on
+    // its poster as a player nobody could start. A host that plays for it
+    // says so in the hello, and `attachPaneChannel` puts the pane's player
+    // here then (src/cocoa/paneplayer.js); one that does not leaves a pane
+    // refusing `src`, its poster shown and `onError` told.
     this._players = new Map();
-    if (canPlay(native)) {
+    const pane = options.pane ?? process.env.REACT_X11_FRAME === '1';
+    if (canPlay(native) && !pane) {
       this.createPlayer = (src, options) => new CocoaPlayer(this, src, options);
     }
 
@@ -522,6 +532,15 @@ export class CocoaApp {
     return new CocoaPaneHost(this, wnd, { send });
   }
 
+  /**
+   * Whether this app plays a pane's `<video src>` for it — the pane host
+   * makes the player and sends its frames down (src/cocoa/paneplayer.js).
+   * What a `<Frame>` tells its pane in the hello.
+   */
+  get playsForPanes() {
+    return !this._paneMode && canPlay(this._native);
+  }
+
   /**
    * Whether this backend drops a control's menu as the platform's own — a
    * bridge with `popUpMenu` (@windowkit/appkit 0.20) — rather than a drawn
@@ -909,9 +928,11 @@ export class CocoaApp {
   /**
    * The pane's end of the frame channel (childmain hands it over,
    * feature-detected so the X11 pane path never notices): geometry and
-   * input come in, pane-present and pane-cursor go out.
+   * input come in, pane-present and pane-cursor go out. `players` is the
+   * host's word that it plays the pane's `<video src>`s, which makes
+   * `createPlayer` here — before the pane's first render, which asks.
    */
-  attachPaneChannel(channel) {
+  attachPaneChannel(channel, { players = false } = {}) {
     if (!this._paneMode) return;
     this._paneSend = (msg) => {
       try {
@@ -920,7 +941,19 @@ export class CocoaApp {
         // the host is going away; its shutdown owns the rest
       }
     };
+    if (players && canShowPanePlayers(this._native)) {
+      this.createPlayer = (src, options) => new PanePlayer(this, src, options);
+    }
     channel.onMessage((msg) => {
+      // a player is the app's, not a window's
+      if (msg?.type === 'pane-player-event') {
+        this._players.get(msg.player)?._event(msg.ev);
+        return;
+      }
+      if (msg?.type === 'pane-player-frame') {
+        this._players.get(msg.player)?._frame(msg);
+        return;
+      }
       const pane = this._paneWindow ?? [...this._windows.values()][0];
       if (!pane) return;
       if (msg?.type === 'pane-rect') {

package/src/cocoa/panehost.js

@@ -8,6 +8,11 @@
 // sheet, a tooltip, a dialog. A pane process runs no AppKit, so each is an
 // NSWindow made here, showing the ring the pane draws it into the same way
 // (`CocoaPaneSubwindow`, src/cocoa/panewindow.js), with its input sent back.
+//
+// And the players its `<video src>`s ask for, which a process with no
+// AppKit would never hear from: each is a player here, its events and its
+// frames sent back (`HostedPlayer`, src/cocoa/paneplayer.js).
+import { HostedPlayer } from './paneplayer.js';
 import { withoutActions } from './quiet.js';
 
 /** One shared surface on glass: a sublayer of a window's root layer, its
@@ -135,6 +140,39 @@ export class CocoaPaneHost extends PaneLayer {
     this._windows = new Map();
     /** @type {Map<number, () => void>} the pane's open menus, by its id */
     this._menus = new Map();
+    /** @type {Map<string, HostedPlayer>} the pane's players, by its id */
+    this._players = new Map();
+  }
+
+  /**
+   * A `pane-player` message: one of the pane's `<video src>`s made, steered
+   * or let go of its player. A player that cannot be made says so the way
+   * one that cannot play does, as a `player-error`.
+   */
+  player(msg) {
+    if (this.destroyed) return;
+    if (msg.op !== 'create') {
+      this._players.get(msg.player)?.handle(msg);
+      if (msg.op === 'release') this._players.delete(msg.player);
+      return;
+    }
+    if (this._players.has(msg.player)) return;
+    try {
+      this._players.set(
+        msg.player,
+        new HostedPlayer(this.app, (m) => this._send?.(m), msg),
+      );
+    } catch (err) {
+      this._send?.({
+        type: 'pane-player-event',
+        player: msg.player,
+        ev: {
+          type: 'player-error',
+          id: msg.player,
+          message: err?.message ?? String(err),
+        },
+      });
+    }
   }
 
   /**
@@ -298,12 +336,15 @@ export class CocoaPaneHost extends PaneLayer {
   }
 
   /** The pane is going, and every window it had here goes with it — a pane
-   * that crashed with a menu open leaves no menu behind. */
+   * that crashed with a menu open leaves no menu behind, and one that
+   * crashed playing leaves no sound. */
   destroy() {
     if (this.destroyed) return;
     for (const cancel of [...this._menus.values()]) cancel();
     this._menus.clear();
     for (const entry of [...this._windows.values()]) this._drop(entry);
+    for (const hosted of this._players.values()) hosted.release();
+    this._players.clear();
     super.destroy();
   }
 }

package/src/cocoa/paneplayer.js

@@ -0,0 +1,336 @@
+// `<video src>` in a `<Frame>` pane on macOS. A pane process runs no
+// NSApplication, so nothing there pumps the bridge's events, and a player it
+// made would open the item and never hear AVFoundation say a word: no size,
+// no play, no frame. So a pane's player is the host's. `PanePlayer` is what
+// the pane's `<video>` holds — the same state and the same verbs as a
+// `CocoaPlayer` — and it sends every verb up the frame channel; the host
+// makes a real `CocoaPlayer` for it (`HostedPlayer`, made by
+// src/cocoa/panehost.js) and sends its events back down.
+//
+// The picture comes down the way a pane's own goes up, the other way round:
+// the host copies the frame showing into one of a ring of shared IOSurfaces
+// (`playerCopyFrame` into a `createSurfaceIOSurface(…, true)` bitmap) and
+// names it, and the pane looks it up by id and copies it into the element's
+// surface when the element asks (`copyFrame`, a `blitSurface` memcpy). A
+// pane has no layers to lift a part onto, so its `<video>` always draws.
+//
+// The ring is three deep because the two processes do not wait on each
+// other: the host writes the buffer after the one it last named, so the one
+// the pane is told about is not written again for two frames — some 66ms at
+// 30fps, against a pane that copies within a display frame of hearing.
+
+import { PlayerState } from './player.js';
+
+// How often the host asks its player for a frame while it plays — the
+// drawn `<video>`'s own cadence (src/nodes/video.js): a copy answers null
+// for a frame that has not changed, so asking every display frame costs a
+// call, and sends nothing.
+const PULL_MS = 16;
+
+// How many times the host asks a paused player for the frame a seek or the
+// item's arrival shows before giving up, a display frame apart: AVFoundation
+// has it a few frames after the event, and a stream that never decodes one
+// should not keep a timer running.
+const WANT_TRIES = 60;
+
+const RING = 3;
+
+let seq = 0;
+
+/** `fn()` with a shared buffer's memory locked for the CPU, as IOSurface
+ *  asks of anything that reads or writes its bytes; the bridge's verbs are
+ *  optional, as they are for the pane's own ring. */
+function locked(native, handle, fn) {
+  const lock = typeof native.surfaceLock === 'function';
+  if (lock) native.surfaceLock(handle);
+  try {
+    return fn();
+  } finally {
+    if (lock) native.surfaceUnlock?.(handle);
+  }
+}
+
+/** Can a pane's player be shown over this bridge? It looks the host's
+ *  buffers up and copies out of them. */
+export function canShowPanePlayers(native) {
+  return (
+    typeof native?.surfaceFromIOSurfaceID === 'function' &&
+    typeof native.blitSurface === 'function'
+  );
+}
+
+/**
+ * The pane's end: a player whose item the host plays. Its state is what
+ * the host's events say; the frame is whichever shared buffer the host
+ * named last, copied out on request.
+ */
+export class PanePlayer extends PlayerState {
+  constructor(app, src, options = {}) {
+    super();
+    this.app = app;
+    this._native = app._native;
+    this.id = `pane-player-${++seq}`;
+    /** the host's newest frame: its buffer here, size and time */
+    this._shown = null;
+    this._fresh = false;
+    /** the host's buffers, looked up: IOSurface id → surface handle */
+    this._buffers = new Map();
+    this._bufferSize = null;
+    app._players.set(this.id, this);
+    this._post({
+      op: 'create',
+      src: String(src),
+      options: {
+        autoPlay: Boolean(options.autoPlay),
+        loop: Boolean(options.loop),
+        muted: Boolean(options.muted),
+        volume: typeof options.volume === 'number' ? options.volume : 1,
+        playbackRate:
+          typeof options.playbackRate === 'number' ? options.playbackRate : 1,
+      },
+    });
+  }
+
+  // held until the host is listening, as the pane's windows are
+  // (`CocoaApp._postWindow`): a `<video>` in the pane's first commit asks
+  // before the host has a pane host to answer
+  _post(msg) {
+    this.app._postWindow({ type: 'pane-player', player: this.id, ...msg });
+  }
+
+  set({ paused, playbackRate, volume, muted, loop } = {}) {
+    if (this.released) return;
+    this._post({
+      op: 'set',
+      settings: { paused, playbackRate, volume, muted, loop },
+    });
+  }
+
+  seek(seconds) {
+    if (this.released || !Number.isFinite(seconds)) return;
+    this.currentTime = Math.max(0, seconds);
+    this._post({ op: 'seek', seconds: this.currentTime });
+  }
+
+  /** The host named a buffer with a new frame in it. */
+  _frame({ surface, width, height, time }) {
+    if (this.released) return;
+    // a ring of another size is a new ring: the old one's buffers are the
+    // host's to free, and these handles only keep them alive
+    if (
+      this._bufferSize?.width !== width ||
+      this._bufferSize?.height !== height
+    ) {
+      this._dropBuffers();
+      this._bufferSize = { width, height };
+    }
+    let handle = this._buffers.get(surface);
+    if (!handle) {
+      try {
+        handle = this._native.surfaceFromIOSurfaceID(surface, 1).handle;
+      } catch {
+        // freed before it got here: the next frame is in another buffer
+        return;
+      }
+      this._buffers.set(surface, handle);
+    }
+    this._shown = { handle, width, height, time };
+    this._fresh = true;
+    // a playing `<video>` asks every display frame; a paused one asks when
+    // its time moves, and the frame a seek shows arrives after the time it
+    // landed on did — so it is told the time again, with the frame in hand
+    if (!this.playing) {
+      this._event({
+        type: 'player-time',
+        id: this.id,
+        currentTime: this.currentTime,
+      });
+    }
+  }
+
+  /** As `CocoaPlayer.copyFrame`: the newest frame into `surface`, or null
+   *  when the host has sent nothing since the last copy. */
+  copyFrame(surface) {
+    const shown = this._shown;
+    if (this.released || !this._fresh || !surface?._surfaceHandle) return null;
+    const { width, height, time } = shown;
+    const fits = surface.width === width && surface.height === height;
+    if (fits) {
+      locked(this._native, shown.handle, () =>
+        this._native.blitSurface(
+          shown.handle,
+          0,
+          0,
+          width,
+          height,
+          surface._surfaceHandle,
+          0,
+          0,
+        ),
+      );
+      this._fresh = false;
+    }
+    return { width, height, time, written: fits };
+  }
+
+  _dropBuffers() {
+    const release = this._native.releaseSurface;
+    if (typeof release === 'function') {
+      for (const handle of this._buffers.values()) {
+        release.call(this._native, handle);
+      }
+    }
+    this._buffers.clear();
+    this._shown = null;
+    this._fresh = false;
+  }
+
+  release() {
+    if (this.released) return;
+    this.released = true;
+    this._listeners.clear();
+    this.app._players.delete(this.id);
+    this._dropBuffers();
+    this._post({ op: 'release' });
+  }
+}
+
+/**
+ * The host's end: a real player for one of the pane's, its events sent down
+ * as they come and its frames copied into the shared ring while it plays —
+ * or, paused, the one frame a seek or the item's arrival shows.
+ */
+export class HostedPlayer {
+  constructor(app, send, { player, src, options }) {
+    this.app = app;
+    this._native = app._native;
+    this._send = send;
+    this.id = player;
+    this.player = app.createPlayer(src, options);
+    this._ring = [];
+    this._ringSize = null;
+    this._next = 0;
+    this._want = 0;
+    this._pull = null;
+    this._off = this.player._subscribe((ev) => this._event(ev));
+  }
+
+  /** A message from the pane about this player. */
+  handle(msg) {
+    const player = this.player;
+    if (player.released) return;
+    if (msg.op === 'set') player.set(msg.settings);
+    else if (msg.op === 'seek') player.seek(msg.seconds);
+    else if (msg.op === 'release') this.release();
+  }
+
+  _event(ev) {
+    this._send({
+      type: 'pane-player-event',
+      player: this.id,
+      ev: { ...ev, id: this.id },
+    });
+    const player = this.player;
+    // a new size is what the next frame is copied at
+    if (ev.type === 'player-metadata') this._ringSize = null;
+    // the item's first frame, and the frame a seek lands on while paused,
+    // are the frames nothing playing would copy
+    if (
+      ev.type === 'player-metadata' ||
+      (ev.type === 'player-time' && !player.playing)
+    ) {
+      this._want = WANT_TRIES;
+      this._copy();
+    }
+    this._syncPull();
+  }
+
+  _syncPull() {
+    const player = this.player;
+    const want = !player.released && (player.playing || this._want > 0);
+    if (want && this._pull === null) {
+      this._pull = setInterval(() => this._copy(), PULL_MS);
+      this._pull.unref?.();
+    } else if (!want && this._pull !== null) {
+      clearInterval(this._pull);
+      this._pull = null;
+    }
+  }
+
+  /** The frame showing into the next buffer of the ring, and the pane told
+   *  which; nothing when the player has nothing new. */
+  _copy() {
+    const player = this.player;
+    if (player.released) return;
+    const size = this._ringSize ?? {
+      width: player.width,
+      height: player.height,
+    };
+    let got = null;
+    if (size.width > 0 && size.height > 0) {
+      const buffer = this._buffer(size.width, size.height);
+      got = locked(this._native, buffer.handle, () =>
+        this._native.playerCopyFrame(player.id, buffer.handle),
+      );
+      if (got?.written) {
+        this._next = (this._next + 1) % RING;
+        this._send({
+          type: 'pane-player-frame',
+          player: this.id,
+          surface: buffer.iosurfaceId,
+          width: got.width,
+          height: got.height,
+          time: got.time,
+        });
+        if (!player.playing) this._want = 0;
+      } else if (got?.width > 0 && got?.height > 0) {
+        // a frame of another size than the ring (a stream that switched
+        // renditions): the next is copied into a ring of its size
+        this._ringSize = { width: got.width, height: got.height };
+      }
+    }
+    if (!got?.written && this._want > 0) this._want -= 1;
+    this._syncPull();
+  }
+
+  /** The ring's next buffer, at `width` x `height`: a new ring at another
+   *  size. Shared, so the pane can look each one up by its id. */
+  _buffer(width, height) {
+    if (
+      this._ring.length === 0 ||
+      this._ring[0].width !== width ||
+      this._ring[0].height !== height
+    ) {
+      this._freeRing();
+      for (let i = 0; i < RING; i += 1) {
+        const made = this._native.createSurfaceIOSurface(
+          width,
+          height,
+          1,
+          true,
+        );
+        this._ring.push({ ...made, width, height });
+      }
+      this._next = 0;
+    }
+    return this._ring[this._next];
+  }
+
+  _freeRing() {
+    const release = this._native.releaseSurface;
+    if (typeof release === 'function') {
+      for (const buffer of this._ring)
+        release.call(this._native, buffer.handle);
+    }
+    this._ring = [];
+  }
+
+  release() {
+    if (this.player.released) return;
+    this._off();
+    this.player.release();
+    this._want = 0;
+    this._syncPull();
+    this._freeRing();
+  }
+}

package/src/cocoa/player.js

@@ -24,24 +24,16 @@ export function canPlay(native) {
 }
 
 /**
- * One file or URL, playing or not. `width`/`height` are the picture's once
- * the item is ready (0 before), `duration` its length in seconds (`Infinity`
- * for a live stream, NaN before it is known).
+ * What a player knows and who hears it: the state its `player-*` events
+ * say, the same whichever process the player is in — this one's
+ * (`CocoaPlayer`), or a `<Frame>` host's on a pane's behalf
+ * (src/cocoa/paneplayer.js). `width`/`height` are the picture's once the
+ * item is ready (0 before), `duration` its length in seconds (`Infinity`
+ * for a live stream, NaN before it is known). A subclass sends `set` and
+ * `seek` on.
  */
-export class CocoaPlayer {
-  constructor(app, src, options = {}) {
-    this.app = app;
-    this._native = app._native;
-    const made = this._native.createPlayer(String(src), {
-      autoPlay: Boolean(options.autoPlay),
-      loop: Boolean(options.loop),
-      muted: Boolean(options.muted),
-      volume: typeof options.volume === 'number' ? options.volume : 1,
-      rate: typeof options.playbackRate === 'number' ? options.playbackRate : 1,
-    });
-    this.id = made.id;
-    /** the AVPlayerLayer, a layer handle */
-    this.layer = made.layer;
+export class PlayerState {
+  constructor() {
     this.width = 0;
     this.height = 0;
     this.duration = NaN;
@@ -51,11 +43,9 @@ export class CocoaPlayer {
     this.error = null;
     this.released = false;
     this._listeners = new Set();
-    app._players.set(this.id, this);
   }
 
-  /** A `player-*` event from the bridge: the state it says, then whoever
-   *  listens. */
+  /** A `player-*` event: the state it says, then whoever listens. */
   _event(ev) {
     if (this.released) return;
     switch (ev.type) {
@@ -96,6 +86,36 @@ export class CocoaPlayer {
     return () => this._listeners.delete(fn);
   }
 
+  play() {
+    // HTML plays an ended item from its start
+    if (this.ended) this.seek(0);
+    this.set({ paused: false });
+  }
+
+  pause() {
+    this.set({ paused: true });
+  }
+}
+
+/** One file or URL, played by this process's bridge. */
+export class CocoaPlayer extends PlayerState {
+  constructor(app, src, options = {}) {
+    super();
+    this.app = app;
+    this._native = app._native;
+    const made = this._native.createPlayer(String(src), {
+      autoPlay: Boolean(options.autoPlay),
+      loop: Boolean(options.loop),
+      muted: Boolean(options.muted),
+      volume: typeof options.volume === 'number' ? options.volume : 1,
+      rate: typeof options.playbackRate === 'number' ? options.playbackRate : 1,
+    });
+    this.id = made.id;
+    /** the AVPlayerLayer, a layer handle */
+    this.layer = made.layer;
+    app._players.set(this.id, this);
+  }
+
   /** What `paused`, `playbackRate`, `volume`, `muted` and `loop` say now;
    *  what is left out stays. */
   set({ paused, playbackRate, volume, muted, loop } = {}) {
@@ -111,16 +131,6 @@ export class CocoaPlayer {
     this._native.playerSet(this.id, settings);
   }
 
-  play() {
-    // HTML plays an ended item from its start
-    if (this.ended) this.seek(0);
-    this.set({ paused: false });
-  }
-
-  pause() {
-    this.set({ paused: true });
-  }
-
   seek(seconds) {
     if (this.released || !Number.isFinite(seconds)) return;
     this.currentTime = Math.max(0, seconds);

package/src/cocoa/promotion.js

@@ -28,7 +28,9 @@
 // square corners cuts the layer to its box, a row half out of its list as
 // much as a spinner inside a card. A scrollbar's thumb drawn over it goes
 // on a layer of its own above it instead (`_syncThumbs`). And no ancestor
-// may fade, because the layer would not be faded with it. Declining is always
+// may fade, because the layer would not be faded with it. Nor may it be in a
+// pane that is scrolling (`_scrolling`): its layer would move every frame
+// the bitmap is painted anyway. Declining is always
 // safe: the frame clock runs the animation exactly as it does without this
 // file. The same test runs again every frame, so a node that becomes
 // overlapped, hidden, clipped, faded or non-plain returns to the bitmap in
@@ -36,6 +38,7 @@
 // loop the clock runs is offered again once the scene would take it
 // (`wouldTake`), where it is in its cycle. docs/macos.md §"Layer
 // promotion" is the account.
+import { now } from '../nodes/animation.js';
 import { BoxNode } from '../nodes/box.js';
 import { addDamageRect, damageToPaint } from '../nodes/damage.js';
 import { intersectRects } from '../nodes/rects.js';
@@ -71,6 +74,19 @@ const THUMB_COLOUR = 'rgba(0, 0, 0, 0.25)';
 // user's attention span for a layer that is only holding still.
 const IDLE_GRACE_MS = 1000;
 
+// How long after a pane last scrolled a node inside it may have a layer
+// again (`_scrolling`). A wheel steps a pane sixty times a second against a
+// display's 75 or 120, so a scroll has still frames in it, and a node
+// promoted in one of those came off its layer again in the next. And a
+// sprinkle of fades on rows scrolled under the pointer is the case it is
+// for: on a 100,000-row table each hovered row kept a layer for the grace,
+// asked again every frame whether it might stay and its raster synced as
+// the pane moved it, and a wheel cost 29% more of every frame than painting
+// the fades in the bitmap did (react-x11-components' perf sweep, round 45).
+// A loop on a row comes off with the rest and is offered again once the
+// pane has been still this long (`wouldTake`).
+const SCROLL_QUIET_MS = 250;
+
 // Past this many bare-rect claims on one raster the passes cost more than
 // the repaint they save (the layer presenter's rule, per raster).
 const MAX_DIRTY_RECTS = 16;
@@ -327,6 +343,8 @@ export class CocoaPromotion {
     // layers are under
     this.thumbs = new Map(); // pane -> Map(axis -> { layer, props })
     this._thumbsWanted = null;
+    // when each scroll pane last scrolled, on the frame clock (`_scrolling`)
+    this._scrolledAt = new WeakMap(); // pane -> ms
     this._claiming = false;
   }
 
@@ -474,6 +492,9 @@ export class CocoaPromotion {
    */
   frame(root, layoutRan) {
     if (layoutRan) this.layoutGen++;
+    // before anything can return early: a still frame between a wheel's
+    // steps has to know the pane was moving in the one before
+    this._noteScrolls(root);
     // 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);
@@ -506,12 +527,16 @@ export class CocoaPromotion {
           const { node, key } = candidates[i];
           if (this.promoted.has(node) || !this.animations.has(node)) continue;
           const cut = { thumbs: new Set(), round: true };
-          const reach = key && promotableNode(node) ? reachOf(node) : null;
+          const scrolling = this._scrolling(node);
+          const reach =
+            key && promotableNode(node) && !scrolling ? reachOf(node) : null;
           if (reach && this._clear(node, reach, cut)) {
             for (const pane of cut.thumbs) wanted.add(pane);
             this._promote(node, root, clipOf(cut, reach));
           } else {
-            this.denied.set(node, this.layoutGen);
+            // a scene answers the same way until it is laid out again; a
+            // scroll is over in a moment, and lays nothing out to say so
+            if (!scrolling) this.denied.set(node, this.layoutGen);
             this.animations.drop(node, true);
           }
         }
@@ -552,6 +577,7 @@ export class CocoaPromotion {
   _mayStay(node, key) {
     if (!key || !promotableNode(node)) return false;
     if (this.releasing.has(node)) return false; // its grace ran out
+    if (this._scrolling(node)) return false;
     const cut = { thumbs: new Set(), round: true };
     const reach = reachOf(node);
     if (!reach || !this._clear(node, reach, cut)) return false;
@@ -573,6 +599,9 @@ export class CocoaPromotion {
     if (this.window.destroyed || node.destroyed) return false;
     if (this.promoted.has(node)) return true;
     if (!promotableNode(node) || !this._paintKey(node)) return false;
+    // asked before the frame, by the window's loop pass
+    this._noteScrolls(node.root);
+    if (this._scrolling(node)) return false;
     const reach = reachOf(node);
     if (!reach) return false;
     if (!this._clear(node, reach, { thumbs: new Set(), round: true })) {
@@ -585,6 +614,30 @@ export class CocoaPromotion {
     return true;
   }
 
+  /** The panes `root`'s frame scrolled: the window keeps them until it
+   *  takes the frame's damage, which is after this. */
+  _noteScrolls(root) {
+    const pending = root?._pendingScrolls;
+    if (!pending?.size) return;
+    const t = now();
+    for (const pane of pending) this._scrolledAt.set(pane, t);
+  }
+
+  /**
+   * Is `node` inside a pane that is scrolling — one that moved this frame,
+   * or within `SCROLL_QUIET_MS` of it? Its layer would move every frame
+   * the pane is painted anyway, and the frame keeps the node in the bitmap,
+   * where a pane's scroll blit carries it.
+   */
+  _scrolling(node) {
+    const t = now();
+    for (let n = node.parent; n && !n.isWindow; n = n.parent) {
+      const at = this._scrolledAt.get(n);
+      if (at !== undefined && t - at < SCROLL_QUIET_MS) return true;
+    }
+    return false;
+  }
+
   _promote(node, root, clip = null) {
     const p = {
       visual: new Visual(this, node),

package/src/cocoa/sprites.js

@@ -27,7 +27,10 @@
 // `@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.
+// element. Or it is CSS's `matrix3d()`, a part turned out of the plane and
+// seen in a perspective, which Core Animation draws through the whole
+// matrix on the GPU: a part none of whose corners is behind the viewer, on a
+// bridge that takes one (`matrix3d`).
 //
 // A part none of which shows — scrolled out of its pane, or outside its own
 // clip — keeps its layer, cut to show nothing, up to a budget of raster for
@@ -68,6 +71,14 @@ const AFTER_CHILDREN = Number.MAX_SAFE_INTEGER;
 
 const IDENTITY = Object.freeze([1, 0, 0, 1, 0, 0]);
 
+// what a part with no bounds may reach (`_underDrawn`)
+const EVERYWHERE = Object.freeze({
+  x: -1e9,
+  y: -1e9,
+  width: 2e9,
+  height: 2e9,
+});
+
 const ORIGIN = Object.freeze({ x: 0, y: 0 });
 
 // what a part with no part lifted inside it is handed
@@ -98,7 +109,20 @@ const isRect = (r) =>
   r.width > 0 &&
   r.height > 0;
 
-const isMatrix = (m) => Array.isArray(m) && m.length === 6 && m.every(finite);
+// CSS's `matrix(a, b, c, d, e, f)`, or its `matrix3d()`'s sixteen numbers
+const isMatrix = (m) =>
+  Array.isArray(m) && (m.length === 6 || m.length === 16) && m.every(finite);
+
+const isSolid = (m) => m.length === 16;
+
+/** Does `sprite` turn out of the plane, at rest or in an animation? */
+function solidSprite(sprite) {
+  if (sprite.transform && isSolid(sprite.transform)) return true;
+  for (const a of sprite.animations ?? []) {
+    if (a.property === 'transform' && a.values.some(isSolid)) return true;
+  }
+  return false;
+}
 
 const isCurve = (t) =>
   typeof t === 'string' ||
@@ -203,12 +227,15 @@ const originOf = (sprite) =>
     y: sprite.rect.y + sprite.rect.height / 2,
   };
 
-/** `rect` through `m` about `origin`: the bounds of its four corners. */
+/** `rect` through `m` about `origin`: the bounds of its four corners, or
+ *  null where `m` is a matrix3d that puts a corner behind the viewer, past
+ *  which the plane's picture has no bounds. */
 function mapRect(rect, m, origin) {
   let x0 = Infinity;
   let y0 = Infinity;
   let x1 = -Infinity;
   let y1 = -Infinity;
+  const solid = isSolid(m);
   for (const [px, py] of [
     [rect.x, rect.y],
     [rect.x + rect.width, rect.y],
@@ -217,8 +244,18 @@ function mapRect(rect, m, origin) {
   ]) {
     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;
+    let x;
+    let y;
+    if (solid) {
+      // column-major, as `matrix3d()` writes it: the point (dx, dy, 0, 1)
+      const w = m[3] * dx + m[7] * dy + m[15];
+      if (!(w > W_NEAR)) return null;
+      x = (m[0] * dx + m[4] * dy + m[12]) / w + origin.x;
+      y = (m[1] * dx + m[5] * dy + m[13]) / w + origin.y;
+    } else {
+      x = m[0] * dx + m[2] * dy + m[4] + origin.x;
+      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;
@@ -227,6 +264,10 @@ function mapRect(rect, m, origin) {
   return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
 }
 
+// A corner whose w is this close to the viewer's plane is as good as behind
+// it: projected that near, it lands off any window.
+const W_NEAR = 1e-6;
+
 function unionRect(a, b) {
   if (!a) return b;
   const x = Math.min(a.x, b.x);
@@ -242,7 +283,8 @@ function unionRect(a, b) {
 /**
  * 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
+ * whole pixels and the antialiasing a raster is padded for — or null, where
+ * one of those puts a corner of it behind the viewer. 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
@@ -271,12 +313,18 @@ function extentOf(sprite) {
   if (about?.key !== key) {
     let box = mapRect(rel, m0, ORIGIN);
     for (const a of sprite.animations ?? []) {
-      if (a.property !== 'transform') continue;
-      for (const m of a.values) box = unionRect(box, mapRect(rel, m, ORIGIN));
+      if (a.property !== 'transform' || !box) continue;
+      for (const m of a.values) {
+        const at = mapRect(rel, m, ORIGIN);
+        box = at && unionRect(box, at);
+        if (!box) break;
+      }
     }
     about = { key, box };
     if (turns) EXTENTS.set(turns, about);
   }
+  // a corner behind the viewer, at rest or on the way: nowhere bounded
+  if (!about.box) return null;
   const box = {
     x: about.box.x + origin.x,
     y: about.box.y + origin.y,
@@ -311,7 +359,31 @@ function rasterRectOf(sprite) {
 }
 
 const sameMatrix = (a, b) =>
-  a === b || (a != null && b != null && a.every((v, i) => v === b[i]));
+  a === b ||
+  (a != null &&
+    b != null &&
+    a.length === b.length &&
+    a.every((v, i) => v === b[i]));
+
+/**
+ * A part's matrix in device pixels as the bridge takes it, in points: its
+ * translation over the scale and, for a matrix3d, its perspective row times
+ * it — S⁻¹·M·S, with S scaling x, y and z, so that a turn and a perspective
+ * of so many CSS pixels look the same at any scale.
+ */
+function inPoints(m, s) {
+  if (!isSolid(m)) {
+    return { matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s] };
+  }
+  const p = m.slice();
+  p[12] /= s;
+  p[13] /= s;
+  p[14] /= s;
+  p[3] *= s;
+  p[7] *= s;
+  p[11] *= s;
+  return { matrix3d: p };
+}
 
 /**
  * The lifted parts of every element in one window: a layer each, its raster,
@@ -326,9 +398,10 @@ export class SpriteLayers {
     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'),
-    );
+    const forms = this.native.transformForms?.();
+    this.supported = Boolean(forms?.includes?.('matrix'));
+    // and a part turned out of the plane, its matrix3d, the same release
+    this.solid = Boolean(forms?.includes?.('matrix3d'));
     // and a video's frames on a layer need its video surfaces
     this.videos = canLiftVideo(this.native);
     this.hosts = new Map(); // element -> Map(key -> state)
@@ -429,7 +502,12 @@ export class SpriteLayers {
           radius: sprite.clip ? (sprite.clipRadius ?? 0) : 0,
           bounds: null,
         };
+        // turned out of the plane, on a bridge that takes no matrix3d
+        if (!this.solid && solidSprite(sprite)) continue;
         const extent = extentOf(sprite);
+        // a corner behind the viewer: the element draws it, which it can cut
+        // where the plane meets the viewer's
+        if (!extent) continue;
         const bounds = cut.clip ? intersectRects(extent, cut.clip) : extent;
         if (parent) {
           // the parent was asked about everywhere it can be, and its layer
@@ -544,8 +622,9 @@ export class SpriteLayers {
         drawn.push(state.extent);
         continue;
       }
-      // the element draws it, where its own clip lets it show
-      const extent = extentOf(sprite);
+      // the element draws it, where its own clip lets it show — anywhere,
+      // for one with a corner behind the viewer and no clip
+      const extent = extentOf(sprite) ?? EVERYWHERE;
       const shows = sprite.clip ? intersectRects(extent, sprite.clip) : extent;
       if (shows) drawn.push(shows);
     }
@@ -776,7 +855,7 @@ export class SpriteLayers {
       }
     }
     if (!sameMatrix(prev.matrix, m)) {
-      out.transform = { matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s] };
+      out.transform = inPoints(m, s);
       any = true;
     }
     if (any) this.native.setLayerProps(state.layer, out);
@@ -843,9 +922,7 @@ export class SpriteLayers {
       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.map((m) => inPoints(m, s))
             : a.values,
         duration: a.duration / 1000,
         id: caId,

package/src/frame/childmain.js

@@ -225,10 +225,14 @@ export async function runFrameChild(transport, options = {}) {
   // (the Cocoa one) takes the channel itself: geometry and input in,
   // presents out. Feature-detected — the X11 pane path has a real window
   // and a real server and needs none of this.
-  root.app.attachPaneChannel?.({
-    send: (msg) => transport.send(msg),
-    onMessage: (cb) => transport.onMessage(cb),
-  });
+  root.app.attachPaneChannel?.(
+    {
+      send: (msg) => transport.send(msg),
+      onMessage: (cb) => transport.onMessage(cb),
+    },
+    // what the host does for the pane that a pane cannot do itself
+    { players: Boolean(hello.players) },
+  );
 
   let closing = false;
   const close = async () => {

package/src/frame/index.js

@@ -412,6 +412,9 @@ export function Frame({
       rect,
       props: s.table.snapshot(p),
       env: bridgedEnv(e, b),
+      // whether this side plays the pane's `<video src>`s for it — the
+      // Cocoa host does, for a pane process that cannot (paneplayer.js)
+      ...(paneApp?.playsForPanes && { players: true }),
     });
 
     return () => {
@@ -613,6 +616,8 @@ function PaneHostView({
         host.popUpMenu?.(msg);
       } else if (msg?.type === 'pane-menu-cancel') {
         host.cancelMenu?.(msg.menu);
+      } else if (msg?.type === 'pane-player') {
+        host.player?.(msg);
       } else if (msg?.type === 'pane-present' && msg.window != null) {
         host.presentWindow?.(msg);
       } else if (msg?.type === 'pane-cursor' && msg.window != null) {

package/src/frame/protocol.js

@@ -6,7 +6,7 @@
 // Six messages, all objects with a `type`:
 //
 //   parent → child
-//     hello    { protocol, src, display, rect, props, env }   first, once
+//     hello    { protocol, src, display, rect, props, env, players? }   first, once
 //     update   { props, env }        full snapshots, one per parent commit
 //     unmount  {}                    run close handlers, unmount, exit
 //

package/src/node.d.ts

@@ -237,6 +237,23 @@ export interface PaintCachePlan {
  */
 export type SpriteMatrix = [number, number, number, number, number, number];
 
+/**
+ * CSS's `matrix3d()`: sixteen numbers, column by column, a point
+ * (x, y, z, 1) going to the first three rows over the fourth — a turn out
+ * of the plane and the perspective it is seen in, about the sprite's
+ * `origin`. Its translation (the 13th to 15th) is in device pixels, and so
+ * is the distance its perspective row divides by. A presenter lifts a
+ * sprite with one only where none of its corners is behind the viewer, at
+ * rest or in any keyframe, and where its bridge takes one.
+ */
+// prettier-ignore
+export type SpriteMatrix3D = [
+  number, number, number, number,
+  number, number, number, number,
+  number, number, 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;
@@ -252,8 +269,9 @@ export interface SpriteAnimation {
   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[];
+   * 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)[];
   /** 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
@@ -321,7 +339,7 @@ export interface Sprite {
   /** 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;
+  transform?: SpriteMatrix | SpriteMatrix3D;
   /** Device pixels, window coordinates; `rect`'s centre when left out. */
   origin?: { x: number; y: number };
   animations?: SpriteAnimation[];

package/src/nodes/sprites.js

@@ -25,9 +25,12 @@ export class NodeSprites {
    * - `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.
+   *   array, `e` and `f` in device pixels, or `matrix3d()`'s sixteen
+   *   numbers for a part turned out of the plane and seen in a perspective
+   *   — 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. A matrix3d part is lifted only where none of its corners is behind
+   *   the viewer, at rest or in any keyframe.
    * - `animations`: what the render server runs on it, each `{ id,
    *   property: 'opacity' | 'transform', values, keyTimes, timings,
    *   duration, delay, repeat, autoreverse, hold }`, with times in