react-x11 2.37.0 → 2.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.37.0",
+  "version": "2.38.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/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
 //