react-x11 2.4.0 → 2.6.0

package/src/cocoa/window.js

@@ -26,6 +26,12 @@ export class CocoaWindow {
     this._surfaceGen = 0;
     this._ctx = null;
     this._dirty = false;
+    // AppKit's occlusion state, as the delegate reports it (`_visible`).
+    this._occluded = false;
+    // This window's frame clock: when it last painted, and how often it may
+    // — the period of the display it is on (`_refreshFrameInterval`).
+    this._rafLast = 0;
+    this._frameInterval = 0;
 
     const s = this.scale;
     // Snapped to whole POINTS: AppKit rounds window sizes to the point
@@ -73,8 +79,18 @@ export class CocoaWindow {
     this.windowNumber = this._native.windowNumber(this._h);
     this._layer = this._native.windowRootLayer(this._h);
     this._refreshOrigin();
+    this._refreshFrameInterval();
     if (attributes.sizeHints) this.setSizeHints(attributes.sizeHints);
 
+    // How many damage rects a frame may keep before merging them (nodes.js,
+    // MAX_DAMAGE_RECTS is the X11 answer). A pass here costs one CoreGraphics
+    // clip and a culled walk, where an X pass costs the server a clip mask,
+    // so a frame in which a clock, a graph and a status row all ticked keeps
+    // the three small rects instead of the box around them — which on a
+    // large tree was most of the window, painted for three cells' worth of
+    // change.
+    this.damageRectCap = 16;
+
     // The retained layer presenter (docs/macos.md Tier L), behind
     // REACT_X11_COCOA_PRESENTER=layers while the surface path is the
     // measured default. Its two hooks exist only in this mode, so the
@@ -115,6 +131,18 @@ export class CocoaWindow {
     this._screenOrigin = { x: this.x, y: this.y };
   }
 
+  /**
+   * How often this window may paint: the period of the display it is on,
+   * asked of the app (`frameIntervalFor`), which reads the screen list the
+   * bridge reported. Re-read whenever the window moves, because a drag
+   * from a 120Hz panel to a 60Hz monitor halves the rate it is worth
+   * painting at — and a window that straddles two answers for the one
+   * under its centre.
+   */
+  _refreshFrameInterval() {
+    this._frameInterval = this.app.frameIntervalFor(this);
+  }
+
   /** Native geometry changed (delegate event, points). */
   _nativeResized(points) {
     const s = this.scale;
@@ -123,6 +151,13 @@ export class CocoaWindow {
     this.x = Math.round(points.x * s);
     this.y = Math.round(points.y * s);
     this._screenOrigin = { x: this.x, y: this.y };
+    this._refreshFrameInterval();
+    // AppKit's inLiveResize, as the delegate reported it: the renderer
+    // answers a live tick with the layout floors it has and measures fresh
+    // ones after the drag (nodes.js, `_deferContentFloors`). Cleared by
+    // the pump (`_endLiveResizes`), because the pump cannot run while the
+    // resize loop owns the thread — a tick of it is the drag being over.
+    if (points.live === true) this.liveResizing = true;
   }
 
   resize(width, height) {
@@ -144,6 +179,7 @@ export class CocoaWindow {
     this.y = Math.round(y);
     this._native.setWindowFrame(this._h, x / s, y / s, null, null);
     this._screenOrigin = { x: this.x, y: this.y };
+    this._refreshFrameInterval();
   }
 
   // --- lifecycle -----------------------------------------------------------
@@ -151,10 +187,17 @@ export class CocoaWindow {
   map() {
     if (this.destroyed) return;
     this.mapped = true;
+    // Showing is a claim that the window is on glass; if it comes up behind
+    // another application's window, AppKit's occlusion event says so on the
+    // next pump and the frames wait from then. Reset here rather than kept,
+    // so a window that was hidden behind one, unmapped and mapped again
+    // does not wait on an event that may already have been delivered.
+    this._occluded = false;
     // A popup must not take the keyboard from its owner; a toplevel's first
     // map is the app coming up and takes it.
     this._native.showWindow(this._h, !this._popup);
     this._refreshOrigin();
+    this._refreshFrameInterval();
   }
 
   unmap() {
@@ -169,7 +212,7 @@ export class CocoaWindow {
     this.mapped = false;
     this.app._unregisterWindow(this);
     this._native.destroyWindow2(this._h);
-    this._surface = null;
+    this._releaseBacking();
   }
 
   // --- window-manager-ish surface (feature-detected by nodes.js) -----------
@@ -232,6 +275,14 @@ export class CocoaWindow {
    * the just-shown frame's damage across — a damage-sized memcpy replacing
    * a window-sized upload. Falls back to the single plain surface where
    * IOSurface creation fails.
+   *
+   * A new size retires the pair, and the retired pair is released on the
+   * spot (`_releaseBacking`): a resize tick allocates two window-sized
+   * IOSurfaces, 20MB at 900x700@2x, and left to the handles' finalizers a
+   * forty-tick drag held 800MB until a collection happened to run — the
+   * `rss +80MB` docs/macos.md measured. The layer keeps its own reference
+   * to whichever IOSurface it is still showing, so the free is safe while
+   * that frame is on glass.
    */
   _ensureSurface() {
     const w = this.width;
@@ -242,7 +293,7 @@ export class CocoaWindow {
       this._surfaceSize?.height !== h
     ) {
       const hadSurface = Boolean(this._surface);
-      this._chain = null;
+      this._releaseBacking();
       try {
         const a = this._native.createSurfaceIOSurface(w, h, this.scale);
         const b = this._native.createSurfaceIOSurface(w, h, this.scale);
@@ -258,20 +309,41 @@ export class CocoaWindow {
       this._surfaceSize = { width: w, height: h };
       this._surfaceGen++;
       this._flushDamage = 'full';
-      // A replaced backing surface holds nothing: whatever bounded damage
-      // this frame carries, everything else on it would be garbage. Ask for
-      // the full frame — one extra repaint per real resize, correctness for
-      // every pixel outside the damage rect.
-      if (hadSurface) {
-        queueMicrotask(() => {
-          const node = this._reactX11Node;
-          if (node && !node.destroyed) node.invalidate(true, null, 'resize');
-        });
-      }
+      // A replaced backing surface holds nothing but what the flush now
+      // painting puts on it. Whether that is enough is decided when the
+      // flush reports its rects (`noteFrameDamage`) — not here, and not by
+      // queueing a full frame behind this one. That used to be the answer,
+      // and it made every tick of a live resize two full frames: the resize
+      // event's own unbounded repaint, then this one, painting the same
+      // pixels again. Worse, inside AppKit's resize loop no microtask runs
+      // until the drag ends, so a drag of forty ticks queued forty full
+      // frames that all ran on the mouse release — the freeze after a
+      // resize, measured at seconds on a large tree.
+      if (hadSurface) this._freshSurface = true;
     }
     return this._surface;
   }
 
+  /**
+   * Free the backing store now — the swapchain pair, or the plain surface
+   * the fallback holds — rather than when V8 collects the handles. Bridges
+   * before 0.4 have no `releaseSurface`; there the finalizer is still the
+   * only owner, and this is the drop it always was.
+   */
+  _releaseBacking() {
+    const release = this._native.releaseSurface;
+    if (typeof release === 'function') {
+      if (this._chain) {
+        release.call(this._native, this._chain.back.handle);
+        release.call(this._native, this._chain.front.handle);
+      } else if (this._surface) {
+        release.call(this._native, this._surface);
+      }
+    }
+    this._chain = null;
+    this._surface = null;
+  }
+
   /**
    * The per-flush painted rects (nodes.js's swapchain seam), accumulated
    * until the next present: they are what the flip's catch-up copy covers.
@@ -279,6 +351,22 @@ export class CocoaWindow {
    */
   noteFrameDamage(rects) {
     if (this._presenter) return;
+    if (this._freshSurface) {
+      this._freshSurface = false;
+      // A full flush painted every pixel of the new surface, and a resize
+      // event's flush is one (nodes.js, the 'resize' listener). A bounded
+      // one left garbage outside its rects: hold the present until the full
+      // frame asked for here lands, so the garbage is never on glass.
+      if (rects) {
+        this._holdPresent = true;
+        const node = this._reactX11Node;
+        if (node && !node.destroyed) node.invalidate(false, null, 'resize');
+      } else {
+        this._holdPresent = false;
+      }
+    } else if (!rects) {
+      this._holdPresent = false;
+    }
     if (this._flushDamage === 'full') return;
     if (!rects) {
       this._flushDamage = 'full';
@@ -287,6 +375,25 @@ export class CocoaWindow {
     (this._flushDamage ??= []).push(...rects);
   }
 
+  /**
+   * Whether anyone can see this window: mapped by the renderer, and not
+   * ordered out or miniaturized by the user. A window that fails this owes
+   * no frames — its callbacks wait in the app's queue (`_tickFrames`) and
+   * its last paint stays unpresented until it is back on glass, where one
+   * catch-up frame covers everything that changed in between.
+   *
+   * Occlusion by another application's window counts too: a window that
+   * is entirely behind one is visible by `isVisible`'s measure and still
+   * costs every frame its tree produces, and AppKit knows the difference.
+   * `windowDidChangeOcclusionState` arrives as the bridge's
+   * `window-occlusion` event (`CocoaApp._routeOcclusion`), `visible` being
+   * "some pixel of it is on glass"; `_occluded` is the last word of it.
+   */
+  _visible() {
+    if (this.destroyed || !this.mapped || this._occluded) return false;
+    return this._native.windowIsVisible(this._h) !== false;
+  }
+
   getContext() {
     if (!this._ctx) {
       this._ctx = new CocoaContext2D(
@@ -345,13 +452,16 @@ export class CocoaWindow {
   }
 
   requestAnimationFrame(cb) {
-    return this.app._requestFrame(cb);
+    return this.app._requestFrame(cb, this);
   }
 
   /** Push the backing surface at the WindowServer, if anything drew. */
   present() {
     if (this._presenter) return; // layers upload as they sync
     if (!this._dirty || !this._surface || this.destroyed) return;
+    // …and if anyone would see it. `_dirty` stays set, so the pump asks
+    // again next tick and the frame goes out the moment the window is back.
+    if (this._holdPresent || !this._visible()) return;
     this._dirty = false;
     if (this._chain) {
       const shown = this._chain.back;

package/src/events.js

@@ -78,7 +78,16 @@ class SyntheticEvent {
     // by, and `localX` below subtracts an `abs` divided the same way
     // (src/scale.js). Everything *internal* — hit testing, drag
     // thresholds, the scroll accumulator — keeps reading `native`.
-    const s = manager.scale;
+    //
+    // **The target's** unit, not the window's, so that a subtree zoomed by
+    // a `scale` prop reads its own: `ev.x` then compares with the target's
+    // `getClientRects()`, which divides by the same factor, and `localX`
+    // lands on the styles that node was written with. This is CSS `zoom`'s
+    // trade-off rather than a transform's, and the corner it costs is
+    // named in docs/scale.md — a handler on an *unzoomed* ancestor reads a
+    // coordinate in the zoomed descendant's unit, because the target is
+    // what decides. `nativeEvent` is the way back to the window's pixels.
+    const s = target?.scale ?? manager.scale;
     this._manager = manager;
     this._targetNode = target;
     this.type = type;
@@ -802,8 +811,14 @@ export class EventManager {
       // `ev.deltaX/Y` are logical (what handlers read); the scroll they
       // become moves device pixels, and truncating *after* the multiply is
       // what keeps the blit on whole device pixels at fractional scales.
-      const owedX = this._wheelOwed.x + ev.deltaX * this.scale;
-      const owedY = this._wheelOwed.y + ev.deltaY * this.scale;
+      // The target's scale, the same unit the event's coordinates are in
+      // (`SyntheticEvent`), so a notch over a subtree zoomed by a `scale`
+      // prop moves a notch of *its* pixels — the content under the pointer
+      // travels the distance the zoom says, which is what CSS `zoom` does
+      // and what a pane whose rows are twice the size needs.
+      const wheelScale = target.scale;
+      const owedX = this._wheelOwed.x + ev.deltaX * wheelScale;
+      const owedY = this._wheelOwed.y + ev.deltaY * wheelScale;
       const dx = Math.trunc(owedX);
       const dy = Math.trunc(owedY);
       this._wheelOwed = { x: owedX - dx, y: owedY - dy };
@@ -822,9 +837,12 @@ export class EventManager {
       for (let n = target; n; n = n.parent) {
         if (n.canScroll?.(dx, dy)) {
           // built-in scrollers take the device delta whole; a registered
-          // element's own scrollBy speaks the public (logical) unit
+          // element's own scrollBy speaks the public (logical) unit — and
+          // *that node's* logical unit, since `scrollBy` multiplies by its
+          // own scale on the way back in, which is the only division that
+          // round-trips exactly across a scale boundary
           if (n._scrollByDevice) n._scrollByDevice(dx, dy);
-          else n.scrollBy({ x: dx / this.scale, y: dy / this.scale });
+          else n.scrollBy({ x: dx / n.scale, y: dy / n.scale });
           break;
         }
         if (n === this.node) break;

package/src/index.d.ts

@@ -180,6 +180,31 @@ export interface RootOptions {
    * is a backend.
    */
   backend?: 'auto' | 'x11' | 'cocoa';
+  /**
+   * The Cocoa backend's knobs (docs/macos.md). `presenter` picks the frame
+   * path: `'surface'` (the measured default — one bitmap per window, the
+   * X11 paint machinery over an IOSurface swapchain) or `'layers'` (one
+   * CALayer per drawn node, opt-in while it is measured).
+   * `frameInterval` is how often a scheduled frame may paint, in ms. By
+   * default each window paces itself on the display it is on — 8.3ms on
+   * a 120Hz panel, 16.7 on a 60Hz monitor, the screen's own refresh rate
+   * as the bridge reports it, 16 where the OS cannot say. A number here
+   * applies to every window instead. `pumpInterval` is the AppKit event
+   * pump's cadence, in ms (8 by default), which is the floor under input
+   * latency. Ignored off macOS and when {@link RootOptions.app} is passed.
+   */
+  cocoa?: {
+    presenter?: 'surface' | 'layers';
+    frameInterval?: number;
+    pumpInterval?: number;
+  };
+  /**
+   * The size, in logical pixels, under which a `<text>` is painted as a
+   * strip of its ink where its lines are instead of as glyphs — a
+   * zoomed-out view's labels, which nobody can read and which cost a glyph
+   * run each. 6 by default; 0 paints glyphs at every size.
+   */
+  textStripBelow?: number;
   /** `':1'`, `'host:0.0'`, or a unix socket path. Defaults to `$DISPLAY`. */
   display?: string;
   /**