react-x11 2.11.0 → 2.13.0

package/src/cocoa/bezels.js

@@ -18,11 +18,44 @@
 // frame padded back out by those insets and blitted from the ink region.
 // Scanned rather than hard-coded so a macOS release that redraws its
 // controls moves the answer instead of breaking it.
+//
+// ## On a worker
+//
+// In threaded mode (src/cocoa/main.js) the bridge makes the control on the
+// UI thread and answers a measure or a draw through a callback
+// (windowkit/appkit#54) — a cell made on the worker drew correct pixels
+// and then crashed the process at exit. So nothing here can ask and use
+// the answer in one call. The metrics layout reads synchronously, `natural`
+// and `shadow`, are fetched for every kind at startup (`prefetch`). A bezel
+// `get` has not drawn yet answers null and calls back once it has, and the
+// caller draws what it had meanwhile. A bezel drawn at rest brings its
+// pressed twin along, so the press — the input whose answer is the bezel —
+// never waits for one (AGENTS.md, "Answer the input").
+
+const KINDS = ['push', 'checkbox', 'radio', 'popup', 'slider', 'switch'];
+// the sizes the widget set lays its controls out at (components/native.js)
+const SIZES = ['regular', 'small'];
+// the fullest state, so the scan sees the whole footprint
+const SCAN_STATE = Object.freeze({
+  state: 1,
+  value: 0.5,
+  enabled: true,
+  appearance: 'light',
+});
+
 export class BezelStore {
-  constructor(native) {
+  /**
+   * `answersLater` says whether the bridge answers through a callback —
+   * asked at each call, since the app knows only once it has started.
+   */
+  constructor(native, { answersLater = () => false } = {}) {
     this._native = native;
+    this._answersLater = answersLater;
     this._canonical = new Map(); // kind|size|scale → { insets, natural }
+    this._scanning = new Map(); // kind|size|scale → the scan in flight
     this._cache = new Map(); // full param key → { surface, sx, sy, sw, sh }
+    this._drawing = new Map(); // full param key → callbacks awaiting it
+    this._gen = 0;
     this._MAX = 160;
   }
 
@@ -40,16 +73,21 @@ export class BezelStore {
   clear() {
     // the surfaces are freed by their External finalizer
     this._cache.clear();
+    // a draw still out is in the old accent: it goes to its callers, and
+    // not into the cache
+    this._gen++;
   }
 
   /**
    * The control's natural size in logical px — the size the bezel is
    * designed at, which layout adopts for the kinds that must not stretch
    * (checkbox, radio, switch). For the stretchable kinds only `height` is
-   * meaningful: a push button is as wide as its label needs.
+   * meaningful: a push button is as wide as its label needs. Null on a
+   * worker for a size `prefetch` did not cover, until its scan is in.
    */
   natural(kind, controlSize = 'regular') {
     const c = this._scan(kind, controlSize, 2);
+    if (!c) return null;
     return {
       width: Math.round(c.natural.width),
       height: Math.round(c.natural.height),
@@ -65,20 +103,38 @@ export class BezelStore {
    */
   shadow(kind, controlSize = 'regular') {
     const c = this._scan(kind, controlSize, 2);
+    if (!c) return { top: 0, bottom: 0 };
     return {
       top: Math.round(c.body.top),
       bottom: Math.round(c.body.bottom),
     };
   }
 
+  /**
+   * Scan every kind at the widget set's sizes, now: at scale 2 for the
+   * metrics (`natural` measures there) and at `scale` for the bezels the
+   * app will draw. Resolves once all are in. For a worker, where a scan is
+   * two answers from the UI thread; on the main thread it is not needed,
+   * each scan running the first time it is asked for.
+   */
+  prefetch(scale) {
+    const jobs = [];
+    for (const s of new Set([2, scale])) {
+      for (const kind of KINDS) {
+        for (const size of SIZES) jobs.push(this._scanLater(kind, size, s));
+      }
+    }
+    return Promise.all(jobs).then(() => undefined);
+  }
+
   /**
    * The bezel for one laid-out box: `w`/`h` in device px, blit-ready.
    * Returns `{ surface, sx, sy, sw, sh }` — draw with the 9-arg
-   * `ctx.drawImage` so the ink region lands exactly on the box.
+   * `ctx.drawImage` so the ink region lands exactly on the box. On a worker
+   * a bezel not drawn yet is null, and `onReady` is called once it is in.
    */
-  get(params, w, h, scale) {
+  get(params, w, h, scale, onReady = null) {
     const controlSize = params.controlSize ?? 'regular';
-    const c = this._scan(params.kind, controlSize, scale);
     const key = JSON.stringify([
       params.kind,
       controlSize,
@@ -92,7 +148,7 @@ export class BezelStore {
       h,
       scale,
     ]);
-    let entry = this._cache.get(key);
+    const entry = this._cache.get(key);
     if (entry) {
       // Map order is the recency order: re-inserting keeps the hot bezels
       // at the young end when the cache is over budget.
@@ -100,6 +156,23 @@ export class BezelStore {
       this._cache.set(key, entry);
       return entry;
     }
+    if (this._answersLater()) {
+      this._drawLater(key, { ...params, controlSize }, w, h, scale, onReady);
+      return null;
+    }
+    const c = this._scan(params.kind, controlSize, scale);
+    const frame = this._frame(c, w, h, scale);
+    this._native.drawControlIntoSurface(frame.surface, {
+      ...params,
+      controlSize,
+    });
+    this._store(key, frame.entry);
+    return frame.entry;
+  }
+
+  /** A surface padded out by the kind's insets, and the region of it a box
+   * `w` × `h` blits from. */
+  _frame(c, w, h, scale) {
     const fw = w / scale + c.insets.left + c.insets.right;
     const fh = h / scale + c.insets.top + c.insets.bottom;
     const surface = this._native.createSurface(
@@ -107,51 +180,123 @@ export class BezelStore {
       Math.max(1, Math.round(fh * scale)),
       scale,
     );
-    this._native.drawControlIntoSurface(surface, {
-      ...params,
-      controlSize,
-    });
-    entry = {
+    return {
       surface,
-      sx: Math.round(c.insets.left * scale),
-      sy: Math.round(c.insets.top * scale),
-      sw: w,
-      sh: h,
+      entry: {
+        surface,
+        sx: Math.round(c.insets.left * scale),
+        sy: Math.round(c.insets.top * scale),
+        sw: w,
+        sh: h,
+      },
     };
+  }
+
+  _store(key, entry) {
     this._cache.set(key, entry);
     if (this._cache.size > this._MAX) {
       // eldest first; the surface itself is freed by its External finalizer
       const oldest = this._cache.keys().next().value;
       this._cache.delete(oldest);
     }
-    return entry;
+  }
+
+  /** A worker's `get`: one draw per key however many ask, each asker called
+   * back when it lands. The surface is left alone until then — the bridge
+   * draws into its bitmap on the UI thread. */
+  _drawLater(key, params, w, h, scale, onReady) {
+    const waiting = this._drawing.get(key);
+    if (waiting) {
+      if (onReady) waiting.add(onReady);
+      return;
+    }
+    const callbacks = new Set(onReady ? [onReady] : []);
+    this._drawing.set(key, callbacks);
+    const gen = this._gen;
+    this._scanLater(params.kind, params.controlSize, scale).then((c) => {
+      const frame = this._frame(c, w, h, scale);
+      this._native.drawControlIntoSurface(frame.surface, params, () => {
+        this._drawing.delete(key);
+        if (gen === this._gen) this._store(key, frame.entry);
+        for (const fn of callbacks) fn();
+        // the twin a press will ask for, drawn before the press
+        if (!params.pressed && params.enabled !== false) {
+          this.get({ ...params, pressed: true }, w, h, scale);
+        }
+      });
+    });
   }
 
   /**
    * One render + alpha scan per (kind, size, scale): where does this cell
    * actually put ink inside the frame it is given? The frame is the natural
    * cellSize widened by 24pt so a stretchable bezel's side margins are
-   * visible as margins rather than crowding the ends.
+   * visible as margins rather than crowding the ends. Null on a worker when
+   * the scan is not in yet: it is asked for, and answers later.
    */
   _scan(kind, controlSize, scale) {
     const key = `${kind}|${controlSize}|${scale}`;
-    let c = this._canonical.get(key);
-    if (c) return c;
+    const done = this._canonical.get(key);
+    if (done) return done;
+    if (this._answersLater()) {
+      this._scanLater(kind, controlSize, scale);
+      return null;
+    }
     const m = this._native.measureControl({ kind, controlSize });
+    const frame = this._scanFrame(m, scale);
+    this._native.drawControlIntoSurface(frame.surface, {
+      kind,
+      controlSize,
+      ...SCAN_STATE,
+    });
+    return this._inkBox(key, frame, scale);
+  }
+
+  /** `_scan` through the bridge's callbacks: once per key, however many
+   * ask. */
+  _scanLater(kind, controlSize, scale) {
+    const key = `${kind}|${controlSize}|${scale}`;
+    const done = this._canonical.get(key);
+    if (done) return Promise.resolve(done);
+    let job = this._scanning.get(key);
+    if (job) return job;
+    const native = this._native;
+    job = new Promise((resolve) =>
+      native.measureControl({ kind, controlSize }, resolve),
+    )
+      .then((m) => {
+        const frame = this._scanFrame(m, scale);
+        return new Promise((resolve) =>
+          native.drawControlIntoSurface(
+            frame.surface,
+            { kind, controlSize, ...SCAN_STATE },
+            () => resolve(frame),
+          ),
+        );
+      })
+      .then((frame) => {
+        this._scanning.delete(key);
+        return this._inkBox(key, frame, scale);
+      });
+    this._scanning.set(key, job);
+    return job;
+  }
+
+  _scanFrame(m, scale) {
     const fw = m.width + 24;
     const fh = m.height;
     const pw = Math.max(1, Math.round(fw * scale));
     const ph = Math.max(1, Math.round(fh * scale));
-    const surface = this._native.createSurface(pw, ph, scale);
-    this._native.drawControlIntoSurface(surface, {
-      kind,
-      controlSize,
-      // the fullest state, so the scan sees the whole footprint
-      state: 1,
-      value: 0.5,
-      enabled: true,
-      appearance: 'light',
-    });
+    return {
+      surface: this._native.createSurface(pw, ph, scale),
+      fw,
+      fh,
+      pw,
+      ph,
+    };
+  }
+
+  _inkBox(key, { surface, fw, fh, pw, ph }, scale) {
     const buf = this._native.ctxGetImageData(surface, 0, 0, pw, ph);
     let x0 = pw;
     let y0 = ph;
@@ -189,7 +334,7 @@ export class BezelStore {
       by0 = y0;
       by1 = y1;
     }
-    c = {
+    const c = {
       insets: {
         left: x0 / scale,
         top: y0 / scale,

package/src/cocoa/dnd.js

@@ -149,28 +149,42 @@ export function requestedAction(operations) {
  * `DropSession.localDrop` hands the handler: `items` by type, the parsed
  * `files`, the best `text`, and a `getData` answering from the same read.
  */
-export function readPayload(native, types) {
+export function readPayload(native, types, carried = null) {
   const values = {};
   const urls = [];
-  const items = (() => {
-    try {
-      return native.dragItems?.() ?? [];
-    } catch {
-      return [];
-    }
-  })();
-  items.forEach((item, index) => {
+  // On a worker the drop carries its payload's text and URL forms itself
+  // (`items: [{ types, strings }]`, windowkit/appkit#51), since the drag
+  // pasteboard cannot be read back from there inside the callback; its
+  // other types are offered, and read as nothing.
+  const read = carried
+    ? {
+        items: carried,
+        string: (index, uti) => carried[index]?.strings?.[uti] ?? null,
+        data: () => null,
+      }
+    : {
+        items: (() => {
+          try {
+            return native.dragItems?.() ?? [];
+          } catch {
+            return [];
+          }
+        })(),
+        string: (index, uti) => native.dragItemString(index, uti),
+        data: (index, uti) => native.dragItemData(index, uti),
+      };
+  read.items.forEach((item, index) => {
     for (const uti of item?.types ?? []) {
       if (uti === 'public.file-url' || uti === 'public.url') {
-        const url = native.dragItemString(index, uti);
+        const url = read.string(index, uti);
         if (url) urls.push(url);
         continue;
       }
       const mime = mimeFromUti(uti, native);
       if (!mime || values[mime] !== undefined) continue;
       const value = isTextual(uti, mime)
-        ? native.dragItemString(index, uti)
-        : native.dragItemData(index, uti);
+        ? read.string(index, uti)
+        : read.data(index, uti);
       if (value == null) continue;
       values[mime] = value;
       if (
@@ -360,7 +374,7 @@ export class CocoaDropTransport {
     const offer = this._offer(ev);
     const extras = drag
       ? drag._dropExtras()
-      : readPayload(this.wnd._native, offer.types);
+      : readPayload(this.wnd._native, offer.types, ev.items ?? null);
     const outcome = this.session.localDrop(offer, extras, Date.now());
     if (drag && outcome.handled) drag.currentAction = outcome.action;
     const response = { accept: outcome.handled };

package/src/cocoa/fonts.js

@@ -17,7 +17,7 @@
 // fontShapeText / fontWithSize / ctxDrawGlyphs).
 //
 // Index spaces, because two meet here: `lines[].start/end` and
-// `runs[].start/end` are UTF-16 code units (what `rangeBands` in nodes.js
+// `runs[].start/end` are UTF-16 code units (what `rangeBands` in nodes/text.js
 // compares against), while `caretPosition()` takes and `indexAt()` returns
 // code points (what the selection and caret code speak). CoreText itself is
 // UTF-16 end to end; the code-point conversion happens at this boundary and
@@ -936,7 +936,7 @@ export class CocoaFontManager {
     }
     // A width offer of zero is a question, not a degenerate layout: yoga
     // asks it to find the node's min-content floor (`minWidth: 'auto'`,
-    // nodes.js). It used to fall into the `undefined` below and answer
+    // nodes/window/floors.js). It used to fall into the `undefined` below and answer
     // max-content — the whole paragraph on one line — so a `<text>` in a
     // flex item held its container open at its longest line and two equal
     // columns came out 823px and 34px wide. `brokenAtEveryOpportunity` is
@@ -944,7 +944,7 @@ export class CocoaFontManager {
     const minContent = Number.isFinite(maxWidth) && maxWidth <= 0;
     // Whether this paragraph is one that ends in a `…`. Both halves: ntk
     // elides off the line *count*, so an ellipsis with nothing to cap can
-    // never fire (nodes.js `_maxLines`), and neither can this.
+    // never fire (nodes/text.js `_maxLines`), and neither can this.
     const elides = overflow === 'ellipsis' && Number.isFinite(maxLines);
     // An eliding paragraph's floor is the mark, not its longest word, and
     // it is cut here because the native cannot cut without a width to cut

package/src/cocoa/glarea.js

@@ -14,7 +14,10 @@
 // `destroy()`, `requestAnimationFrame`. On X11 that child is a real X
 // window stacked above the parent's drawing; here it is a sublayer of the
 // window's root layer with a high zPosition — the same "GL sits above the
-// 2D" semantics, by the same mechanism the platform gives us.
+// 2D" semantics, by the same mechanism the platform gives us. The layer
+// takes no input: pointer events are the NSWindow's, and the window's hit
+// test answers the surface for a point over it (`GlAreaNode.hitSurface`),
+// which is where X11's event propagation ends up too.
 //
 // ## The API ladder
 //
@@ -142,7 +145,6 @@ export class CocoaGLArea {
     this.scale = this.parent.scale ?? app.scale ?? 1;
     this.destroyed = false;
     this._reactX11Node = null;
-    this.onWheel = options.onWheel ?? null;
     this.layer = this._native.createLayer();
     this._native.addSublayer(this.parent._layer, this.layer);
     this.rect = null;
@@ -161,7 +163,7 @@ export class CocoaGLArea {
     if (this.destroyed) return;
     this.rect = rect;
     const s = this.scale;
-    this._native.setLayerProps(this.layer, {
+    this._setLayerProps({
       frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
       // above both presenters' content: the surface presenter's contents
       // live on the root layer itself, the layers presenter's visuals top
@@ -193,8 +195,25 @@ export class CocoaGLArea {
   }
 
   map() {
-    if (!this.destroyed) {
-      this._native.setLayerProps(this.layer, { hidden: false });
+    if (!this.destroyed) this._setLayerProps({ hidden: false });
+  }
+
+  /**
+   * Everything this layer is handed goes out with Core Animation's implicit
+   * actions off. The layer is ours, not a presenter's, so no frame's
+   * transaction covers it, and a bare set animates each key for a quarter
+   * of a second from wherever the layer was: the surface grew into place
+   * at mount and trailed every step of a live resize. A present needs
+   * nothing here — `setLayerContentsIOSurface` opens its own transaction
+   * for the flip.
+   */
+  _setLayerProps(props) {
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.setLayerProps(this.layer, props);
+    } finally {
+      native.txCommit();
     }
   }
 

package/src/cocoa/main.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `react-x11/cocoa-main` — the cocoa backend's threaded mode, a side-effect
+ * entry for `node --import` (`bun --preload`): the app's entry runs on a
+ * worker while AppKit keeps the main thread, so menus, drags, live resizes
+ * and modal panels no longer stop the app's JS. Does nothing off macOS.
+ * No exports.
+ */
+export {};

package/src/cocoa/main.js

@@ -0,0 +1,43 @@
+// react-x11/cocoa-main — threaded mode asked for by name, for `--import`:
+//
+//   node --import react-x11/cocoa-main app.jsx
+//   bun --preload react-x11/cocoa-main app.jsx
+//
+// Threaded mode is the default on macOS without it: the first import of
+// react-x11 moves the app onto a worker (src/cocoa/relaunch.js). This does
+// the same before the entry is even loaded, and skips the checks that keep
+// the automatic move from firing where it should not — so it is the way in
+// for an app the automatic move declines (react-x11 imported late, say),
+// and it spares the main thread from loading the entry's imports once for
+// nothing (docs/packaging.md).
+//
+// On the worker it starts, Node runs this `--import` again, before the
+// entry, and it sets the worker up there — earlier than the package's own
+// import would (Bun does not apply a `--preload` to a Worker, and gets the
+// import's). Anywhere else it does nothing, so one command line serves
+// every platform: on Linux the entry runs as it would without it, and so
+// does a Worker the app starts itself (it inherits this `--import`).
+import { isMainThread, workerData } from 'node:worker_threads';
+
+import { loadNative } from './native.js';
+import { bootstrapWorker, relaunch } from './relaunch.js';
+
+if (!isMainThread && workerData?.reactX11State) {
+  bootstrapWorker(workerData.reactX11State);
+} else if (isMainThread && process.platform === 'darwin') {
+  const entry = process.argv[1];
+  if (!entry) {
+    throw new Error(
+      'react-x11/cocoa-main: no entry script to run — start the app with ' +
+        '`node --import react-x11/cocoa-main app.js`.',
+    );
+  }
+  const native = loadNative();
+  if (typeof native.runMain !== 'function') {
+    throw new Error(
+      'react-x11/cocoa-main: the installed @windowkit/appkit has no ' +
+        'runMain() — threaded mode needs bridge 0.10 or later.',
+    );
+  }
+  relaunch(entry, native);
+}

package/src/cocoa/overlay.js

@@ -0,0 +1,159 @@
+// The pane a `<glarea>`'s children are drawn on, on the Cocoa backend: a
+// transparent bitmap layer over the surface (src/gloverlay.js).
+//
+// A sublayer of the window's root layer like the surface's own
+// (src/cocoa/glarea.js), one step above it: the GL layer sits at zPosition
+// 1e7, over everything both presenters put on the root layer, and this one
+// at 1e7 + 1, over that. Core Animation composites it, so what the children
+// leave transparent shows the GL frame, and a translucent fill, an
+// antialiased edge or a shadow blends with it — the one backend where the
+// overlay is not opaque. Every surface's GL layer shares the one zPosition,
+// so where two surfaces overlap, both overlays are above both frames.
+//
+// It speaks the verbs of a window the overlay drives on X11 — `setState`,
+// `map`, `unmap`, `getContext`, `destroy` — plus `present`, which puts what
+// was painted on the layer: ntk blits an X window's backing store on its
+// own, where a layer's contents are a copy the bitmap has to be pushed to.
+import { CocoaContext2D } from './context2d.js';
+
+export const OVERLAY_Z = 1e7 + 1;
+
+export class CocoaOverlayPane {
+  constructor(app, options) {
+    this.app = app;
+    this.parent = options.parent;
+    this._native = app._native;
+    this.scale = this.parent.scale ?? app.scale ?? 1;
+    this.destroyed = false;
+    this.layer = this._native.createLayer();
+    this._native.addSublayer(this.parent._layer, this.layer);
+    this.rect = null;
+    this._surface = null;
+    this._surfaceSize = null;
+    this._gen = 0;
+    this._ctx = null;
+    this._dirty = false;
+    // Hidden until something is on it: a layer shows its contents from the
+    // moment it is added, and before the first present there are none to
+    // show, only whatever the render server makes of that.
+    this._presented = false;
+    this._hidden = false;
+    this.setState({
+      x: options.x ?? 0,
+      y: options.y ?? 0,
+      width: options.width ?? 1,
+      height: options.height ?? 1,
+    });
+  }
+
+  get width() {
+    return this.rect?.width ?? 0;
+  }
+
+  get height() {
+    return this.rect?.height ?? 0;
+  }
+
+  /** Geometry in device px, the unit the overlay's rects are in. */
+  setState(rect) {
+    if (this.destroyed) return;
+    this.rect = rect;
+    const s = this.scale;
+    this._setLayerProps({
+      frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
+      zPosition: OVERLAY_Z,
+      hidden: this._hidden || !this._presented,
+    });
+  }
+
+  map() {
+    this._hidden = false;
+    if (this._presented) this._setLayerProps({ hidden: false });
+  }
+
+  unmap() {
+    this._hidden = true;
+    this._setLayerProps({ hidden: true });
+  }
+
+  /** Implicit animations off, for the reason `CocoaGLArea._setLayerProps`
+   * gives: no frame's transaction covers a layer that is not a presenter's. */
+  _setLayerProps(props) {
+    if (this.destroyed) return;
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.setLayerProps(this.layer, props);
+    } finally {
+      native.txCommit();
+    }
+  }
+
+  /** The bitmap, the pane's size — a new size is a new bitmap, cleared, and
+   * the old one freed now rather than by the handle's finalizer. */
+  _ensureSurface() {
+    const w = Math.max(1, this.rect?.width ?? 1);
+    const h = Math.max(1, this.rect?.height ?? 1);
+    const size = this._surfaceSize;
+    if (!this._surface || size.width !== w || size.height !== h) {
+      this._release();
+      this._surface = this._native.createSurface(w, h, this.scale);
+      this._native.ctxClearRect(this._surface, 0, 0, w, h);
+      this._surfaceSize = { width: w, height: h };
+      this._gen++;
+    }
+    return this._surface;
+  }
+
+  _release() {
+    const surface = this._surface;
+    this._surface = null;
+    if (surface && typeof this._native.releaseSurface === 'function') {
+      this._native.releaseSurface(surface);
+    }
+  }
+
+  getContext() {
+    if (!this._ctx) {
+      this._ctx = new CocoaContext2D(
+        this._native,
+        () => this._ensureSurface(),
+        () => {
+          this._ensureSurface();
+          return this._gen;
+        },
+      );
+      this._ctx._fonts = this.app.fonts;
+      this._ctx._onDirty = () => {
+        this._dirty = true;
+      };
+    }
+    return this._ctx;
+  }
+
+  /** What was painted, onto the layer — a copy, so the bitmap is free to be
+   * painted again at once. */
+  present() {
+    if (this.destroyed || !this._dirty || !this._surface) return;
+    this._dirty = false;
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.surfaceToLayer(this._surface, this.layer);
+      if (!this._presented) {
+        this._presented = true;
+        if (!this._hidden) native.setLayerProps(this.layer, { hidden: false });
+      }
+    } finally {
+      native.txCommit();
+    }
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this._release();
+    this._ctx = null;
+    this._native.removeFromSuperlayer(this.layer);
+  }
+}

package/src/cocoa/panehost.js

@@ -29,11 +29,21 @@ export class CocoaPaneHost {
       return;
     }
     this._rect = { ...rect };
-    this._native.setLayerProps(this.layer, {
-      frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
-      zPosition: 1e7,
-      hidden: false,
-    });
+    // Actions off: the layer is ours, not a presenter's, so no frame's
+    // transaction covers it, and a bare set tweens the pane into place at
+    // mount and after every resize — the trap CocoaGLArea._setLayerProps
+    // describes.
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.setLayerProps(this.layer, {
+        frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
+        zPosition: 1e7,
+        hidden: false,
+      });
+    } finally {
+      native.txCommit();
+    }
   }
 
   /**