react-x11 2.36.0 → 2.38.0

package/package.json

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

package/src/appearance.js

@@ -135,12 +135,22 @@ const SAME = (a, b) =>
  * and a re-render per announcement would be churn with nothing behind it.
  */
 function publish(values, source) {
+  // **A pin is a pin.** A rung can answer long after it was asked — the
+  // ladder a test started before releasing its pin, a watcher's next line, a
+  // portal signal — and its answer lands in whatever test is running by
+  // then. Taken, that turns the next test's pixels into this machine's
+  // desktop, which is the one thing the pin exists to prevent.
+  if (owner === 'test' && source !== 'test') return;
   const next = Object.freeze({ ...NOTHING, ...values, source });
   if (SAME(next, snapshot)) return;
   snapshot = next;
-  // What came *off* the disk does not go back onto it, and a pinned test
-  // value must never reach a developer's real cache file.
-  if (source !== 'cache' && source !== 'test') save(next);
+  // Only what a rung answered is remembered. What came *off* the disk does
+  // not go back onto it, a pinned test value must never reach a developer's
+  // real cache file — and nor must the defaults a released pin falls back
+  // to (`source: null`), which every `cleanup()` publishes: written, they
+  // replaced the developer's remembered desktop after every test, and their
+  // next app drew its first frame in the wrong colours.
+  if (source && source !== 'cache' && source !== 'test') save(next);
   for (const fn of [...watchers]) {
     try {
       fn(snapshot);
@@ -162,27 +172,42 @@ function publish(values, source) {
  * Pass `null` to release the pin and let the ladder run again.
  */
 export function setAppearanceForTests(values) {
-  probe = null;
-  // Never touch the developer's own remembered answer either, in either
-  // direction: `publish` will not write a pinned value, and marking the cache
-  // as already checked keeps `load()` from reading one back over it.
-  cacheChecked = true;
   if (values === null) {
-    cacheChecked = false;
     // Releasing undoes a *pin*, and only a pin. A real rung's answer is not
     // this function's to throw away: `cleanup()` releases after every test,
     // and a suite that resolved the appearance for real would otherwise find
-    // it wiped by the harness that was meant to leave it alone.
-    if (owner === 'test') {
-      owner = null;
-      publish({}, null);
-    }
+    // it wiped by the harness that was meant to leave it alone — or, with
+    // the cache marked unread, replaced on the next read by what the disk
+    // says, which is a verified answer turned back into a remembered one.
+    if (owner !== 'test') return;
+    owner = null;
+    probe = null;
+    // Unpinned, the remembered answer is this machine's to read again —
+    // intact, because neither the pin nor this release is ever written
+    // (`publish`).
+    cacheChecked = false;
+    publish({}, null);
     return;
   }
+  probe = null;
+  // Never touch the developer's own remembered answer either, in either
+  // direction: `publish` will not write a pinned value, and marking the cache
+  // as already checked keeps `load()` from reading one back over it.
+  cacheChecked = true;
   owner = 'test';
   publish(values, 'test');
 }
 
+/**
+ * What is pinned right now, or null where nothing is. `react-x11/test`'s
+ * `setAppearance` merges over it, so changing one value keeps the rest of the
+ * pin — and asks the store rather than keeping a copy, which a direct
+ * `setAppearanceForTests` call would leave stale.
+ */
+export function pinnedAppearanceForTests() {
+  return owner === 'test' ? snapshot : null;
+}
+
 // --------------------------------------------------------------------------
 // The last known answer
 // --------------------------------------------------------------------------
@@ -929,6 +954,11 @@ async function runWatcher() {
         answered = true;
         publish(values, 'macos');
         done(true);
+        // Refused, because a test pinned the store while this was starting
+        // (`publish`): nothing will hear this watcher again, and while it
+        // lives the rung starts no other — so the ladder that runs once the
+        // pin is released would find the Mac silent.
+        if (owner === 'test') proc.kill();
       }
     };
     proc.stdout.setEncoding?.('utf8');
@@ -1020,7 +1050,10 @@ async function runLadder(app) {
       answered = false;
     }
     if (answered) {
-      owner = name;
+      // A pin set while this rung was being asked keeps the store: the
+      // rung's answer was refused (`publish`), and owning it would hand the
+      // rung's live updates a store they must not write to.
+      if (owner !== 'test') owner = name;
       return snapshot;
     }
   }

package/src/appearancehooks.js

@@ -73,7 +73,7 @@ export function useAppearanceWhen(enabled) {
  * | `selection` | the fill under a selected menu or list row — a darker cut of the accent on macOS — or **null** |
  * | `contrast` | `'normal'` or `'high'` |
  * | `reducedMotion` | `true` when the user asked for less animation |
- * | `source` | `'portal'`, `'xsettings'`, `'macos'`, `'cache'`, or null |
+ * | `source` | `'portal'`, `'xsettings'`, `'macos'`, `'windows'`, `'cache'`, `'test'` (pinned by `react-x11/test`), or null |
  *
  * **`'no-preference'` means use your own default**, not "use light". And
  * `accent` is null far more often than not, so fall back to your own brand

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
 //

package/src/testing/harness.js

@@ -10,7 +10,10 @@
 import React from 'react';
 import { createRoot } from '../Reconciler.js';
 import { setAnimationClock } from '../nodes/animation.js';
-import { setAppearanceForTests } from '../appearance.js';
+import {
+  pinnedAppearanceForTests,
+  setAppearanceForTests,
+} from '../appearance.js';
 
 // A test process must not register with the desktop's live AT-SPI registry —
 // a suite on a developer desktop would otherwise parade hundreds of phantom
@@ -140,10 +143,26 @@ export async function renderX11(element, options = {}) {
     wrap = element?.type !== 'window',
     title = 'react-x11 test',
     colorScheme = 'light',
+    appearance = null,
     a11y = false,
     ...rootOptions
   } = options;
 
+  // Checked before anything is created, so a mistake costs no server
+  const pin = appearancePin(colorScheme, appearance);
+  if (setBeforeMount) {
+    const values = setBeforeMount;
+    setBeforeMount = null;
+    throw new Error(
+      'react-x11/test: setAppearance() was called before renderX11(), which ' +
+        'pins the appearance as it mounts — the values it set would be ' +
+        'replaced without a word. Pass them to the render instead:\n\n' +
+        `  await renderX11(<App />, { appearance: ${JSON.stringify(values)} });\n\n` +
+        'setAppearance() is for changing them once the tree is mounted. ' +
+        'See docs/testing.md#the-desktops-appearance.',
+    );
+  }
+
   let server = null;
   let app = options.app ?? null;
   if (!app) {
@@ -161,14 +180,9 @@ export async function renderX11(element, options = {}) {
   // on a light desktop, red on a dark one, with nothing in the test saying
   // so. After the app exists, so it wins over `createMockApp`'s own pin.
   // `colorScheme: 'dark'` renders the other palette; `'system'` releases the
-  // pin, for a test that is *about* what the desktop reports.
-  setAppearanceForTests(
-    colorScheme === 'system'
-      ? null
-      : colorScheme === 'dark'
-        ? { colorScheme: 'dark' }
-        : {},
-  );
+  // pin, for a test that is *about* what the desktop reports; `appearance`
+  // pins the rest of what `useSystemAppearance()` reports.
+  setAppearanceForTests(pin);
 
   const root = await createRoot({ app, ...rootOptions });
 
@@ -374,6 +388,131 @@ export async function cleanup() {
   // change, every mounted root repaints on one, and a repaint scheduled onto
   // a connection that is about to close lands after it has.
   setAppearanceForTests(null);
+  setBeforeMount = null;
+}
+
+// --- the desktop's appearance ----------------------------------------------
+
+/**
+ * What a test may pin, and what each value may be — the fields
+ * `useSystemAppearance()` reports, less `source`, which reads `'test'` for as
+ * long as anything is pinned.
+ *
+ * Checked rather than passed through, because the store takes anything: a
+ * `reduceMotion: true` would pin nothing, render the component the way it
+ * always does, and pass a test that was meant to prove the opposite.
+ */
+const APPEARANCE = {
+  colorScheme: [
+    (v) => v === 'light' || v === 'dark' || v === 'no-preference',
+    "'light', 'dark' or 'no-preference'",
+  ],
+  accent: [colourOrNull, "a CSS colour such as '#ed5b00', or null"],
+  accentText: [colourOrNull, "a CSS colour such as '#ffffff', or null"],
+  selection: [colourOrNull, "a CSS colour such as '#c96003', or null"],
+  palette: [
+    (v) => v === null || (typeof v === 'object' && !Array.isArray(v)),
+    'an object of palette tokens, or null',
+  ],
+  contrast: [(v) => v === 'normal' || v === 'high', "'normal' or 'high'"],
+  reducedMotion: [(v) => typeof v === 'boolean', 'true or false'],
+};
+
+function colourOrNull(value) {
+  return value === null || (typeof value === 'string' && value !== '');
+}
+
+function checkAppearance(values, where) {
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    throw new TypeError(
+      `react-x11/test: ${where} takes an object of appearance values, such ` +
+        `as { reducedMotion: true } — got ${String(values)}.`,
+    );
+  }
+  for (const [key, value] of Object.entries(values)) {
+    if (key === 'source') {
+      throw new TypeError(
+        `react-x11/test: ${where} cannot set \`source\` — a pinned ` +
+          "appearance reports 'test', which is how a component can tell " +
+          'one from a desktop that answered.',
+      );
+    }
+    const rule = APPEARANCE[key];
+    if (!rule) {
+      throw new TypeError(
+        `react-x11/test: ${where} has no appearance value \`${key}\`. ` +
+          `The values are ${Object.keys(APPEARANCE).join(', ')} — the ` +
+          'fields useSystemAppearance() reports.',
+      );
+    }
+    if (!rule[0](value)) {
+      throw new TypeError(
+        `react-x11/test: ${where}: \`${key}\` is ${rule[1]}, not ` +
+          `${JSON.stringify(value) ?? String(value)}.`,
+      );
+    }
+  }
+  return values;
+}
+
+/** `renderX11`'s two appearance options → the pin, or null to release. */
+function appearancePin(colorScheme, appearance) {
+  if (colorScheme === 'system') {
+    if (appearance) {
+      throw new TypeError(
+        "react-x11/test: renderX11 was given colorScheme: 'system', which " +
+          'follows the real desktop, and `appearance`, which pins it. Pass ' +
+          'one: pin `colorScheme` inside `appearance`, or drop `appearance` ' +
+          'to follow the desktop.',
+      );
+    }
+    return null;
+  }
+  if (colorScheme !== 'light' && colorScheme !== 'dark') {
+    throw new TypeError(
+      "react-x11/test: renderX11's colorScheme is 'light' (the default), " +
+        `'dark' or 'system', not ${JSON.stringify(colorScheme)}.`,
+    );
+  }
+  return {
+    // Light is pinned as "the desktop said nothing", which resolves to the
+    // light palette and is what the mock app pins too
+    ...(colorScheme === 'dark' ? { colorScheme: 'dark' } : {}),
+    ...(appearance ? checkAppearance(appearance, 'renderX11 appearance') : {}),
+  };
+}
+
+/** Values set with nothing mounted, which the next `renderX11` would lose. */
+let setBeforeMount = null;
+
+/**
+ * Change the pinned appearance under a mounted tree, and flush what it
+ * changed — the re-render of everything reading `useSystemAppearance()`, the
+ * palette's repaint, and the frame — the way `userEvent` flushes an input.
+ *
+ * Merged over what is pinned: `setAppearance({ reducedMotion: true })` under
+ * a `colorScheme: 'dark'` render stays dark. Where nothing is pinned
+ * (`colorScheme: 'system'`), it pins these values over the defaults rather
+ * than over this machine's answer, so the result is the test's alone.
+ *
+ * ```js
+ * await renderX11(<Spinner />, { appearance: { reducedMotion: true } });
+ * await setAppearance({ reducedMotion: false });
+ * ```
+ *
+ * The appearance is the desktop's, so it is one for the process: every
+ * mounted root sees the change, as every window would. `cleanup()` releases
+ * it, and a pinned value is never written to the cache the next run of a
+ * real app reads.
+ */
+export async function setAppearance(values) {
+  checkAppearance(values, 'setAppearance()');
+  // `source` comes along and does not matter: the pin overwrites it
+  const next = { ...pinnedAppearanceForTests(), ...values };
+  if (mounted.size === 0) setBeforeMount = { ...setBeforeMount, ...values };
+  await act(() => {
+    setAppearanceForTests(next);
+  });
 }
 
 // --- the animation clock ---------------------------------------------------

package/src/testing/index.d.ts

@@ -5,6 +5,7 @@
 
 import type { ReactNode } from 'react';
 import type { DrawnNode, NtkApp, NtkWindow } from '../types/nodes.js';
+import type { SystemAppearance } from '../types/appearance.js';
 import type { ModifierName } from '../keysyms.js';
 
 export * from '../keysyms.js';
@@ -29,6 +30,14 @@ export interface TestServer {
 /** ntk's 2d context. Pixel helpers take it; `renderX11` hands it back. */
 export type TestContext2D = unknown;
 
+/**
+ * The desktop's appearance as a test pins it: any of the values
+ * `useSystemAppearance()` reports, except `source`, which reads `'test'` for
+ * as long as anything is pinned. A key outside these throws, so a typo cannot
+ * pin nothing and pass.
+ */
+export type PinnedAppearance = Partial<Omit<SystemAppearance, 'source'>>;
+
 export interface RenderX11Options {
   /** Window size (default 640×480). */
   width?: number;
@@ -59,6 +68,21 @@ export interface RenderX11Options {
   title?: string;
   /** Render into a connection you already have. */
   app?: NtkApp;
+  /**
+   * The desktop's colour scheme, **pinned** so a pixel assertion means the
+   * same on every machine. `'light'` (the default) and `'dark'` pick the
+   * built-in palette; `'system'` releases the pin, for a test that is about
+   * what the real desktop reports.
+   */
+  colorScheme?: 'light' | 'dark' | 'system';
+  /**
+   * The rest of the desktop's appearance, pinned from the first render:
+   * reduced motion, contrast, the accent. Merged over `colorScheme`, so
+   * `appearance.colorScheme` wins where both name one; it cannot be combined
+   * with `colorScheme: 'system'`. To change it while mounted, use
+   * `setAppearance()`.
+   */
+  appearance?: PinnedAppearance;
   /**
    * Install the assistive-technology spy before the mount and hand it back
    * as `at`: an in-process log of everything a screen reader would have
@@ -288,9 +312,30 @@ export function renderX11(
  */
 export function act(fn?: () => unknown): Promise<void>;
 
-/** Unmount everything, restore the animation clock, close every server. */
+/**
+ * Unmount everything, restore the animation clock, release the pinned
+ * appearance, close every server.
+ */
 export function cleanup(): Promise<void>;
 
+/**
+ * Change the pinned appearance under a mounted tree and flush what it moved:
+ * every component reading `useSystemAppearance()` re-renders, the palette
+ * repaints, and the frame lands — the way `userEvent` flushes an input.
+ *
+ * Merged over what is pinned, so `setAppearance({ reducedMotion: true })`
+ * under a `colorScheme: 'dark'` render stays dark. The appearance is the
+ * desktop's and so one per process: every mounted root sees the change.
+ * Calling it before `renderX11()` is an error at that render, which pins as
+ * it mounts — pass `appearance` to the render instead.
+ *
+ * ```ts
+ * await renderX11(<Spinner />, { appearance: { reducedMotion: true } });
+ * await setAppearance({ reducedMotion: false });
+ * ```
+ */
+export function setAppearance(values: PinnedAppearance): Promise<void>;
+
 /** Drain in-flight requests on a connection. */
 export function settle(app: NtkApp, roundTrips?: number): Promise<void>;
 

package/src/testing/index.js

@@ -30,6 +30,7 @@ import { setDefaultTarget } from './events.js';
 export {
   act,
   cleanup,
+  setAppearance,
   settle,
   waitFor,
   withFrameClock,

package/src/types/appearance.d.ts

@@ -20,10 +20,10 @@ export type ColorSchemePreference = 'system' | 'light' | 'dark';
  *
  * `'cache'` is the answer this machine gave last time, read off disk before
  * the first render so it does not start from the defaults. A real rung
- * replaces it a moment later.
+ * replaces it a moment later. `'test'` is a value `react-x11/test` pinned.
  */
 export type AppearanceSource =
-  'portal' | 'xsettings' | 'macos' | 'cache' | null;
+  'portal' | 'xsettings' | 'macos' | 'windows' | 'cache' | 'test' | null;
 
 export interface SystemAppearance {
   readonly colorScheme: ColorScheme;