react-x11 2.5.0 → 2.6.1

package/src/cocoa/presenter.js

@@ -19,12 +19,19 @@
 //
 // Sibling order is zPosition, assigned from the node's own paintOrder() —
 // no sublayer-list surgery, ever. Dirt arrives on the invalidate channel
-// (`noteInvalidate`): a node means that node, null means everything (the
-// same "no bound named repaints everything" rule the X11 damage model has),
-// and geometry is re-diffed every frame because comparing four numbers is
-// cheaper than knowing.
+// (`noteInvalidate`): a node means that node, a bare rect means that part
+// of every raster it touches, null means everything (the same "no bound
+// named repaints everything" rule the X11 damage model has), and geometry
+// is re-diffed every frame because comparing four numbers is cheaper than
+// knowing.
 import { cssColorStraight } from 'ntk';
 
+import {
+  Node,
+  addDamageRect,
+  damageToPaint,
+  intersectRects,
+} from '../nodes.js';
 import { CocoaContext2D } from './context2d.js';
 
 const RASTER_PAD = 2; // antialiasing/italic overhang outside the ink bounds
@@ -254,8 +261,27 @@ class ShapeRecorder {
   }
 }
 
-/** Paint everything a node draws itself — Node.paint minus the children. */
+/**
+ * Paint everything a node draws itself — Node.paint minus the children.
+ *
+ * An element that overrides `paint` (every drawing element in
+ * @react-x11/components does: `super.paint(ctx)` for the box, then the
+ * scene) has its content nowhere but in that override, so the override is
+ * what a raster replays — with the children held back by `_ownPaintOnly`,
+ * the one presenter-side flag `Node._paintChildren` honours, because they
+ * have visuals of their own. Everything else paints piecewise, which is
+ * what `Node.paint` would do minus the child walk.
+ */
 function paintSelf(node, ctx) {
+  if (node.paint !== Node.prototype.paint) {
+    node._ownPaintOnly = true;
+    try {
+      node.paint(ctx);
+    } finally {
+      node._ownPaintOnly = false;
+    }
+    return;
+  }
   node._paintShadow(ctx);
   node._paintBackground(ctx);
   node.paintContent(ctx);
@@ -263,6 +289,26 @@ function paintSelf(node, ctx) {
   node._paintOutline(ctx);
 }
 
+// Past this many bare-rect claims in one frame the overlap test costs more
+// than it saves, and the answer is the one a null claim gives: everything.
+const MAX_DIRTY_RECTS = 64;
+
+// The pass list of a raster that repaints in full: one pass, unbounded.
+const FULL_PASS = Object.freeze([null]);
+
+/** A rect grown outward to whole pixels — a pass clears and clips to its
+ * edges, and a fractional edge would antialias the clip into a seam. */
+function wholePixels(rect) {
+  const x = Math.floor(rect.x);
+  const y = Math.floor(rect.y);
+  return {
+    x,
+    y,
+    width: Math.ceil(rect.x + rect.width) - x,
+    height: Math.ceil(rect.y + rect.height) - y,
+  };
+}
+
 const EDGE_PROPS = [
   'borderTopColor',
   'borderRightColor',
@@ -354,6 +400,9 @@ class RasterState {
 
   ensure(presenter, width, height, scale) {
     if (!this.surface || this.width !== width || this.height !== height) {
+      // the layer holds its own copy of what it shows, so the bitmap a
+      // resize retires can go now rather than with the handle's finalizer
+      this.release(presenter.native);
       this.surface = presenter.native.createSurface(width, height, scale);
       this.width = width;
       this.height = height;
@@ -369,6 +418,16 @@ class RasterState {
     }
     return this.ctx;
   }
+
+  /** Free the bitmap now (bridge 0.4's `releaseSurface`); older bridges
+   * free it from the handle's finalizer, and this is then just the drop. */
+  release(native) {
+    const surface = this.surface;
+    this.surface = null;
+    if (surface && typeof native.releaseSurface === 'function') {
+      native.releaseSurface(surface);
+    }
+  }
 }
 
 export class CocoaLayerPresenter {
@@ -380,8 +439,14 @@ export class CocoaLayerPresenter {
     this.visuals = new Map(); // node -> Visual
     this.rasters = new Map(); // node -> RasterState
     this.bars = new Map(); // scroller node -> Map(axis -> { layer, raster })
-    this.dirty = new Set();
+    // Claims since the last frame — taken at the top of `frame()`, the way
+    // the X11 path takes its damage before painting, so a claim made from
+    // inside a paint lands in the next frame instead of being cleared with
+    // this one.
+    this.dirty = new Set(); // nodes
+    this.dirtyRects = []; // bare rects, window coordinates
     this.dirtyAll = true; // first frame rasters everything
+    this._claims = null; // the frame in progress: { all, nodes, rects }
     this.rootVisual = {
       layer: window._layer,
     };
@@ -402,12 +467,77 @@ export class CocoaLayerPresenter {
       // say which node that was. Everything re-rasters; a scroll names its
       // node and stays off this path.
       this.dirtyAll = true;
+    } else if (damage.width > 0 && damage.height > 0) {
+      // A bare rect with no layout behind it is a claim about pixels — an
+      // element's `invalidate(false, rect)` for the box a dragged node
+      // moved through, the region `scrollContents` shifts, the strip an
+      // animation ticks in — and it cannot name the node it came from
+      // either. The frame repaints that part of every raster visual whose
+      // ink the rect touches (the same conservative answer the damage model
+      // gives a rect: whatever draws there repaints, clipped to it);
+      // property boxes carry no raster and re-diff every frame regardless.
+      // Copied, because a caller's rect is very often a live `abs` about
+      // to be laid out.
+      if (this.dirtyRects.length >= MAX_DIRTY_RECTS) {
+        this.dirtyAll = true;
+      } else {
+        this.dirtyRects.push({
+          x: damage.x,
+          y: damage.y,
+          width: damage.width,
+          height: damage.height,
+        });
+      }
     }
   }
 
+  /** The claims a frame consumes, cleared for the next one. */
+  _takeClaims() {
+    const claims = {
+      all: this.dirtyAll,
+      nodes: this.dirty,
+      rects: this.dirtyAll ? [] : this.dirtyRects,
+    };
+    this.dirtyAll = false;
+    this.dirty = new Set();
+    this.dirtyRects = [];
+    return claims;
+  }
+
+  /**
+   * What this frame repaints of the raster covering `rect` for `node`: null
+   * for nothing, `FULL_PASS` for all of it, otherwise the window-space rects
+   * the frame's bare claims cover inside it, shaped exactly as the X11 path
+   * shapes its damage list: whole pixels, disjoint, at most a few of them,
+   * and one box instead of several when the several fill most of it —
+   * because a node painted in two overlapping passes blends translucent ink
+   * over itself, and because each pass is a full replay of the node's paint
+   * that only its own culling makes cheap. A pan's shifted region and the
+   * two strips beside it come out as the one pass they are.
+   */
+  _rasterPasses(node, rect, sizeChanged) {
+    const claims = this._claims;
+    if (sizeChanged || !claims || claims.all || claims.nodes.has(node)) {
+      return FULL_PASS;
+    }
+    let passes = null;
+    for (const claimed of claims.rects) {
+      const hit = intersectRects(wholePixels(claimed), rect);
+      if (hit) passes = addDamageRect(passes, hit);
+    }
+    return passes && damageToPaint(passes);
+  }
+
+  /** Does this frame re-raster the visual covering `rect` for `node`? */
+  _needsRaster(node, rect) {
+    return this._rasterPasses(node, rect, false) !== null;
+  }
+
   /** The whole frame: one walk, one transaction, property diffs only. */
   frame(windowNode) {
     const native = this.native;
+    const claims = (this._claims = this._takeClaims());
+    let presented = false;
     native.txBegin({ disableActions: true });
     try {
       this._syncWindowBackground(windowNode);
@@ -417,21 +547,42 @@ export class CocoaLayerPresenter {
         if (!seen.has(node)) {
           visual.destroy();
           this.visuals.delete(node);
-          this.rasters.delete(node);
+          this._dropRaster(node);
           const bars = this.bars.get(node);
           if (bars) {
             for (const entry of bars.values()) {
               native.removeFromSuperlayer(entry.layer);
+              entry.raster.release(native);
             }
             this.bars.delete(node);
           }
         }
       }
+      presented = true;
     } finally {
       native.txCommit();
+      this._claims = null;
+      // a frame that threw half-way presents what it got to; the claims it
+      // was answering are still owed, so the next frame answers them again
+      if (!presented) this._restoreClaims(claims);
     }
-    this.dirty.clear();
-    this.dirtyAll = false;
+  }
+
+  _restoreClaims(claims) {
+    this.dirtyAll ||= claims.all;
+    for (const node of claims.nodes) this.dirty.add(node);
+    if (this.dirtyRects.length + claims.rects.length > MAX_DIRTY_RECTS) {
+      this.dirtyAll = true;
+    } else {
+      this.dirtyRects.push(...claims.rects);
+    }
+  }
+
+  _dropRaster(node) {
+    const raster = this.rasters.get(node);
+    if (!raster) return;
+    raster.release(this.native);
+    this.rasters.delete(node);
   }
 
   _syncWindowBackground(windowNode) {
@@ -460,7 +611,7 @@ export class CocoaLayerPresenter {
     let visual = this.visuals.get(node);
     if (visual && visual.isRaster !== wantsRaster) {
       visual.destroy();
-      this.rasters.delete(node);
+      this._dropRaster(node);
       visual = null;
     }
     if (!visual) {
@@ -590,9 +741,8 @@ export class CocoaLayerPresenter {
     const s = this.scale;
     if (
       !sizeChanged &&
-      !this.dirtyAll &&
-      !this.dirty.has(node) &&
-      visual.shapeSignature
+      visual.shapeSignature &&
+      !this._needsRaster(node, rect)
     ) {
       return true; // shapes are current
     }
@@ -738,13 +888,38 @@ export class CocoaLayerPresenter {
       }
       this._dropSvgShapes(visual);
     }
-    if (!this.dirtyAll && !this.dirty.has(node) && !sizeChanged) return;
+    const passes = this._rasterPasses(node, rect, sizeChanged);
+    if (!passes) return;
     const ctx = raster.ensure(this, rect.width, rect.height, this.window.scale);
+    // The bitmap is this visual's composition cache, the way the window's
+    // backing store is the surface presenter's: a pass over part of it
+    // clears and clips to that part and leaves the rest as last frame drew
+    // it, and `paintDamage()` names the pass, so an element culls a drag
+    // step or an animation tick exactly as it does on X11 (docs/extending.md,
+    // "Drawing a scene into one node") instead of replaying its whole scene
+    // into a clip that throws almost all of it away. The full pass is the
+    // same loop with nothing to clip.
+    const root = node.root;
     ctx.save();
     try {
-      ctx.clearRect(0, 0, rect.width, rect.height);
       ctx.translate(-rect.x, -rect.y);
-      paintSelf(node, ctx);
+      for (const pass of passes) {
+        const area = pass ?? rect;
+        ctx.save();
+        try {
+          if (pass) {
+            ctx.beginPath();
+            ctx.rect(area.x, area.y, area.width, area.height);
+            ctx.clip();
+          }
+          ctx.clearRect(area.x, area.y, area.width, area.height);
+          if (root) root._paintDamage = pass;
+          paintSelf(node, ctx);
+        } finally {
+          if (root) root._paintDamage = null;
+          ctx.restore();
+        }
+      }
     } finally {
       ctx.restore();
     }

package/src/cocoa/surface.js

@@ -33,9 +33,11 @@
 //   composite differently.
 // - **No Picture.** `picture()` is X's compositing handle; here a surface
 //   composites through `ctx.drawImage`, and asking for the picture says so.
-// - **Freed on collection.** The bridge frees the bitmap from the handle's
-//   finalizer; `destroy()` drops the handle and refuses further use, so the
-//   memory goes with the next GC rather than on the call.
+// - **Freed on `destroy()`.** The bridge's `releaseSurface` (0.4) frees the
+//   bitmap on the call and hands its bytes back to V8's account; the
+//   handle's finalizer stays as the safety net for a surface that is
+//   dropped without one. Under an older bridge the memory goes with the
+//   next GC, as it always did.
 //
 // Units are device pixels, like the window's backing store: a caller sizes
 // one from `contentBox()` numbers, which are device pixels already
@@ -217,8 +219,12 @@ export class CocoaSurface {
   destroy() {
     if (this._destroyed) return;
     this._destroyed = true;
+    const handle = this._surfaceHandle;
     this._surfaceHandle = null;
     this._ctx = null;
+    if (typeof this._native.releaseSurface === 'function') {
+      this._native.releaseSurface(handle);
+    }
   }
 
   [Symbol.dispose]() {

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