react-x11 2.8.3 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.8.3",
+  "version": "2.9.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -98,7 +98,7 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.6.0",
+    "@windowkit/appkit": "^0.7.0",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.7.0"
   },

package/src/Reconciler.js

@@ -33,6 +33,7 @@ import {
   windowAttributes,
   setTextStripBelow,
 } from './nodes.js';
+import { setFrameRateDefault } from './pacing.js';
 import { hasDropProps } from './dnd.js';
 import { AppProvider } from './appcontext.js';
 import {
@@ -796,6 +797,12 @@ export async function createRoot(options = {}) {
   // default, 0 for glyphs at every size.
   setTextStripBelow(app, rest.textStripBelow);
 
+  // How this root's windows pace their frames when their content changes
+  // faster than the display refreshes (src/pacing.js): `'display'` — every
+  // frame the clock gives — unless the root says otherwise; a window's own
+  // `frameRate` prop wins over this, and REACT_X11_FRAME_RATE over both.
+  setFrameRateDefault(app, rest.frameRate);
+
   // Whether a subtree coming back out of hiding — a `<Suspense>` boundary
   // resolving, an `<Activity>` shown again — takes the keyboard back with it
   // (src/events.js, `subtreeRevealed`). On by default; `false` is the

package/src/cocoa/app.js

@@ -537,8 +537,25 @@ export class CocoaApp {
     for (const wnd of this._windows.values()) wnd.liveResizing = false;
   }
 
+  /**
+   * `requestAnimationFrame`, for a window or for the app's own clock. A
+   * frame asked for between two pump ticks used to wait for the next tick
+   * to look at it — up to a pump interval on top of whatever the clock
+   * owed. Now, while the pump runs, the first request into an empty queue
+   * arms the same one-shot a tick arms for a frame it just missed
+   * (`_armFrameTimer`), at the moment the clock is due; a request for a
+   * clock due after the next tick leaves it to the tick, as before. What
+   * a frame is and how many there are does not change — the clock still
+   * gates every one — only when it is looked at, which is what makes a
+   * paced claim (src/pacing.js) land at its wait rather than at its wait
+   * rounded up to the pump.
+   */
   _requestFrame(cb, wnd = null) {
     this._rafQueue.push({ cb, wnd });
+    if (this._pump && this._rafQueue.length === 1) {
+      const now = performance.now();
+      this._armFrameTimer(Math.max(1, this._frameWait(wnd ?? this, now)), now);
+    }
     return this._rafQueue.length;
   }
 

package/src/cocoa/context2d.js

@@ -85,13 +85,23 @@ const clamp01 = (v) => Math.min(1, Math.max(0, Number(v) || 0));
 /**
  * The Render ops text draws with, numbered as XRender numbers them so a
  * caller's `ctx.Render?.PictOp?.Over ?? 3` reads the same on both
- * backends. Every op draws as Over here: the bridge composites glyph
- * coverage with the context's fill and offers no blend-mode switch, and
- * for the opaque inks text uses Src and Over agree.
+ * backends. The `op` a `drawGlyphs` call names is ignored here: the bridge
+ * composites glyph coverage with the context's fill through the context's
+ * own blend mode — `globalCompositeOperation`, below — and for the opaque
+ * inks text uses Src and Over agree.
  */
 const PICT_OP = Object.freeze({ Src: 1, Over: 3 });
 const RENDER = Object.freeze({ PictOp: PICT_OP });
 
+/**
+ * `_state.clip` when the clip in force is not one this class can name — a
+ * rounded corner, a glyph, an arc, or a rect under a rotation. Null means
+ * nothing is clipped and a rect means that rect, in surface pixels; this
+ * means "there is one and I cannot tell you where", which is the answer
+ * that turns the memcpy blit off (see `_blit`).
+ */
+const NON_RECT = Symbol('non-rectangular clip');
+
 /**
  * The path, recorded alongside the native one, so `stroke` can re-issue it
  * in pieces — `CGContextStrokePath` is QUADRATIC in the number of subpaths
@@ -189,7 +199,18 @@ export class CocoaContext2D {
       shadowOffsetY: 0,
       shadowColor: 'rgba(0,0,0,0)',
       ctm: [1, 0, 0, 1, 0, 0],
+      gco: 'source-over',
+      // null: nothing clipped. A rect (surface pixels): that rect. NON_RECT:
+      // a clip this class cannot name.
+      clip: null,
     };
+    // What this bridge can do, asked once. Both verbs arrived together in
+    // @windowkit/appkit 0.7.0, and anything older is a bridge that draws
+    // every composite as `source-over` through a CGImage — so the property
+    // refuses what it cannot honour rather than lying about it, and the
+    // blit path is simply never taken.
+    this._blendModes = typeof native.ctxSetBlendMode === 'function';
+    this._blits = typeof native.blitSurface === 'function';
     this._onDirty = null;
     // the recorded path, and whether the native one still matches it (a
     // chunked stroke leaves only its last chunk behind)
@@ -211,6 +232,13 @@ export class CocoaContext2D {
       n.ctxSetLineJoin(surface, st.lineJoin);
       n.ctxSetGlobalAlpha(surface, st.globalAlpha);
       n.ctxSetLineDash(surface, st.dash, st.dashOffset);
+      // a fresh surface is already at source-over, so only a context
+      // holding another op has anything to say
+      if (this._blendModes && st.gco !== 'source-over') {
+        n.ctxSetBlendMode(surface, st.gco);
+      }
+      // a fresh surface is unclipped, whatever the old one had in force
+      st.clip = null;
       this._stack.length = 0;
       // the path went with the surface it was built on; nothing may
       // replay it onto the new one
@@ -282,6 +310,47 @@ export class CocoaContext2D {
     }
   }
 
+  get globalCompositeOperation() {
+    return this._state.gco;
+  }
+
+  /**
+   * The vocabulary is the **bridge's**, not a table kept here: the names are
+   * canvas's own, `ctxSetBlendMode` answers false for one it does not have,
+   * and that answer is what decides whether the assignment sticks. So this
+   * class never goes stale against a bridge that grows an op, and never
+   * claims one it would not actually draw.
+   *
+   * Which makes the detection a caller writes canvas's own — an unknown
+   * value is *ignored* there too, leaving the op in force — so the way to
+   * ask is to assign and read back:
+   *
+   *     ctx.globalCompositeOperation = 'copy';
+   *     if (ctx.globalCompositeOperation === 'copy') { ... }
+   *
+   * A bridge with no `ctxSetBlendMode` at all — @windowkit/appkit before
+   * 0.7.0 — draws everything as source-over, so source-over is the one
+   * value that sticks on it. That is exactly true rather than a fallback.
+   *
+   * One divergence from a browser, shared with ntk and so the same on both
+   * backends: an op applies inside what the draw covers, not across the
+   * whole surface. A browser's `copy` clears everything the drawing missed;
+   * `kCGBlendModeCopy` and XRender's `Src` both leave it alone.
+   */
+  set globalCompositeOperation(value) {
+    if (typeof value !== 'string') return;
+    if (!this._blendModes) {
+      if (value === 'source-over') this._state.gco = value;
+      return;
+    }
+    // false is the bridge saying it left its own mode alone; anything else
+    // means the mode is now `value`, and the two must not drift — a JS state
+    // ahead of the native one would take the memcpy path in `_blit` for a
+    // composite the fallback draw would have blended.
+    if (this._native.ctxSetBlendMode(this._s(), value) === false) return;
+    this._state.gco = value;
+  }
+
   /**
    * Whether a stroke of a path with many subpaths may go out as several
    * `CGContextStrokePath` calls — on by default, because the alternative
@@ -776,9 +845,70 @@ export class CocoaContext2D {
     ) {
       return;
     }
+    this._state.clip = this._clipAfter();
     this._native.ctxClip(this._path());
   }
 
+  /**
+   * The current path as a whole-pixel rect in surface coordinates, or null
+   * for anything else. CoreGraphics owns the real clip and this is only a
+   * shadow of it, kept for the one caller that draws *around* the context —
+   * `_blit`, whose memcpy cannot see a CGContext's clip at all.
+   *
+   * So the answer has to be exact, never merely close: a rect that does not
+   * land on whole pixels is refused rather than rounded, because rounding
+   * out would copy pixels the clip excludes and rounding in would leave a
+   * seam of whatever the destination held. The clips a paint pass actually
+   * sets — the damage rect, a scroll viewport, a square-cornered `overflow`
+   * — are whole pixels under a translate, and those are the ones this
+   * recognises.
+   */
+  _pathRect() {
+    const cmds = this._cmds;
+    if (cmds.length !== 5 || cmds[0] !== P_RECT) return null;
+    const [, x, y, w, h] = cmds;
+    const [a, b, c, d, e, f] = this._state.ctm;
+    if (b !== 0 || c !== 0) return null; // rotated or skewed: not a rect here
+    const x0 = a * x + e;
+    const y0 = d * y + f;
+    const x1 = a * (x + w) + e;
+    const y1 = d * (y + h) + f;
+    const rect = {
+      x: Math.min(x0, x1),
+      y: Math.min(y0, y1),
+      width: Math.abs(x1 - x0),
+      height: Math.abs(y1 - y0),
+    };
+    for (const v of [rect.x, rect.y, rect.width, rect.height]) {
+      if (!Number.isInteger(v)) return null;
+    }
+    return rect;
+  }
+
+  /** The clip `clip()` is about to leave in force: the current one
+   *  intersected with the path, or NON_RECT as soon as either is one. */
+  _clipAfter() {
+    const current = this._state.clip;
+    if (current === NON_RECT) return NON_RECT;
+    const rect = this._pathRect();
+    if (!rect) return NON_RECT;
+    if (!current) return rect;
+    const x = Math.max(current.x, rect.x);
+    const y = Math.max(current.y, rect.y);
+    return {
+      x,
+      y,
+      width: Math.max(
+        0,
+        Math.min(current.x + current.width, rect.x + rect.width) - x,
+      ),
+      height: Math.max(
+        0,
+        Math.min(current.y + current.height, rect.y + rect.height) - y,
+      ),
+    };
+  }
+
   fillRect(x, y, w, h) {
     if (!(w > 0) || !(h > 0)) return;
     const style = this._state.fillStyle;
@@ -843,10 +973,96 @@ export class CocoaContext2D {
       dw = sw;
       dh = sh;
     }
-    this._native.ctxDrawSurface(this._s(), src, sx, sy, sw, sh, dx, dy, dw, dh);
+    if (!this._blit(src, sx, sy, sw, sh, dx, dy, dw, dh)) {
+      this._native.ctxDrawSurface(
+        this._s(),
+        src,
+        sx,
+        sy,
+        sw,
+        sh,
+        dx,
+        dy,
+        dw,
+        dh,
+      );
+    }
     this._dirty();
   }
 
+  /**
+   * `drawImage` as a row memcpy, for the one shape where a copy is all it
+   * ever was: a surface composited into another at a translate, whole
+   * pixels, same size in as out, under `globalCompositeOperation = 'copy'`.
+   * Answers false for everything else, and the caller draws.
+   *
+   * That shape is what an element with a surface of its own presents every
+   * frame — a terminal's grid, a retained scene — and the CoreGraphics
+   * route to it is `CGBitmapContextCreateImage` of the whole source plus
+   * `CGContextDrawImage`: 1.7ms of a 6ms frame for a 125x45 terminal, where
+   * the memcpy is 1.0 (sidorares/react-x11-components#69 §6). The saving is
+   * per frame rather than per flood, which is why the frame pacer (#497)
+   * had to land first for it to be worth anything.
+   *
+   * Every condition below is a way the memcpy would differ from the draw,
+   * and a difference is a bug rather than a slower frame — so each is a
+   * refusal, never a fixup:
+   *
+   * - **the op.** Only `copy` writes the source over the destination
+   *   without reading it. `source-over` is a blend, and blending is what
+   *   CoreGraphics is for.
+   * - **the transform.** A pure translate at whole pixels. A scale or a
+   *   rotation resamples; a fractional offset resamples too (surfaces are
+   *   created with `kCGInterpolationMedium`).
+   * - **`globalAlpha`, and a shadow.** Both are things `CGContextDrawImage`
+   *   does to the source on its way down that a memcpy does not do at all.
+   * - **the clip.** A memcpy cannot see a CGContext's clip, so the rect it
+   *   copies is intersected with the one this class tracked — and a clip it
+   *   could not track (NON_RECT) means it does not know, so it draws.
+   * - **the same surface twice.** Overlapping memcpy rows have no defined
+   *   result. The check here is on the handle; the bridge's is on the
+   *   backing store, which also catches two handles onto one bitmap — the
+   *   two ends of a shared IOSurface — and throws rather than corrupting it.
+   */
+  _blit(src, sx, sy, sw, sh, dx, dy, dw, dh) {
+    if (!this._blits) return false;
+    const st = this._state;
+    if (st.gco !== 'copy') return false;
+    if (st.clip === NON_RECT) return false;
+    if (st.globalAlpha < 1) return false;
+    if (st.shadowBlur > 0 && parseColor(st.shadowColor)[3] > 0) return false;
+    if (sw !== dw || sh !== dh) return false;
+    const [a, b, c, d, e, f] = st.ctm;
+    if (a !== 1 || b !== 0 || c !== 0 || d !== 1) return false;
+    const x = dx + e;
+    const y = dy + f;
+    if (
+      !Number.isInteger(x) ||
+      !Number.isInteger(y) ||
+      !Number.isInteger(sx) ||
+      !Number.isInteger(sy) ||
+      !Number.isInteger(sw) ||
+      !Number.isInteger(sh)
+    ) {
+      return false;
+    }
+    const dst = this._s();
+    if (dst === src) return false;
+    const clip = st.clip;
+    this._native.blitSurface(
+      src,
+      sx,
+      sy,
+      sw,
+      sh,
+      dst,
+      x,
+      y,
+      clip ? [clip.x, clip.y, clip.width, clip.height] : null,
+    );
+    return true;
+  }
+
   /**
    * Browser contract: a blank RGBA pixel block for the caller to fill and
    * hand back to putImageData. Pure allocation — nothing touches the

package/src/cocoa/window.js

@@ -574,13 +574,28 @@ export class CocoaWindow {
     return this.app._requestFrame(cb, this);
   }
 
-  /** Push the backing surface at the WindowServer, if anything drew. */
+  /**
+   * Push the backing surface at the WindowServer, if anything drew — and
+   * tell the window node what it cost. The flip is cheap; the catch-up
+   * copy behind it is a damage-sized memcpy, and on a window whose every
+   * frame repaints most of itself that is a millisecond of the JS thread
+   * per frame that the flush never saw. The frame pacer prices the frame
+   * by the thread's time, so the present reports in (src/pacing.js,
+   * `WindowNode._notePresentCost`).
+   */
   present() {
-    if (this._presenter) return; // layers upload as they sync
-    if (!this._dirty || !this._surface || this.destroyed) return;
+    const started = performance.now();
+    if (!this._presentNow()) return;
+    this._reactX11Node?._notePresentCost?.(performance.now() - started);
+  }
+
+  /** The present itself: true when a frame reached the layer. */
+  _presentNow() {
+    if (this._presenter) return false; // layers upload as they sync
+    if (!this._dirty || !this._surface || this.destroyed) return false;
     // …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;
+    if (this._holdPresent || !this._visible()) return false;
     this._dirty = false;
     if (this._chain) {
       const shown = this._chain.back;
@@ -608,7 +623,7 @@ export class CocoaWindow {
             ]),
       );
       if (this._transparentWindow) this.app._shadowStale.add(this);
-      return;
+      return true;
     }
     this._native.surfaceToLayer(this._surface, this._layer);
     // AppKit derives a transparent window's shadow from the content's
@@ -619,6 +634,7 @@ export class CocoaWindow {
     // the frame BEFORE this one and keeps the square rim for menus that
     // paint once and are only hovered after.
     if (this._transparentWindow) this.app._shadowStale.add(this);
+    return true;
   }
 
   snapshot(path) {

package/src/debug.js

@@ -399,7 +399,7 @@ function createSession({ sink, path }) {
       }
     },
 
-    frame({ rects, reasons, start, end, landed }) {
+    frame({ rects, reasons, start, end, landed, waited }) {
       frames += 1;
       const full = !rects;
       const area = full
@@ -421,7 +421,12 @@ function createSession({ sink, path }) {
         // timings cannot show. Either way it is paint-vs-everything-else.
         const wait =
           typeof landed === 'number' ? ` landed=${landed.toFixed(1)}ms` : '';
-        line(`frame ${frames}: ${where}${why}${wait}`);
+        // How long the frame pacer held this frame's claim before letting
+        // the clock have it (src/pacing.js) — only under an adaptive
+        // `frameRate`, and only for a frame that was held, so the default
+        // path's lines are the lines they always were.
+        const held = waited > 0 ? ` waited=${waited.toFixed(1)}ms` : '';
+        line(`frame ${frames}: ${where}${why}${wait}${held}`);
       }
       record({
         name: 'frame',
@@ -437,6 +442,7 @@ function createSession({ sink, path }) {
           area,
           reasons: reasons ?? [],
           landedMs: typeof landed === 'number' ? +landed.toFixed(2) : undefined,
+          waitedMs: waited > 0 ? +waited.toFixed(2) : undefined,
         },
       });
     },

package/src/glnodes.js

@@ -11,6 +11,7 @@ import { cssColorStraight } from 'ntk';
 export { directGLFailure, hasDirectGL } from './glbackend.js';
 
 import { Node } from './nodes.js';
+import { FramePacer, resolveFrameRate } from './pacing.js';
 
 // One visual query per (app, spec): GetFBConfigs is a round trip and every
 // <glarea> in an app wants the same answer.
@@ -99,6 +100,9 @@ const px = (v) => Math.max(1, Math.round(v || 0));
  * - `clearColor` — CSS colour or `[r, g, b, a]` floats (default black).
  * - `frameLoop` — `'demand'` (default: redraw on prop/size/expose changes)
  *   or `'always'` (drive ntk's frame clock continuously).
+ * - `frameRate` — how the frames are paced when they are expensive
+ *   (src/pacing.js): a preset, a cap, or the three numbers, the same
+ *   vocabulary as `<window frameRate>`. Defaults to the owning window's.
  * - `glx` — a `chooseGLXConfig` spec, e.g. `{ DEPTH_SIZE: 24 }`.
  *
  * The X child window is stacked above everything drawn in the parent, so 2D
@@ -114,12 +118,36 @@ export class GlAreaNode extends Node {
     this._frameScheduled = false;
     this._created = false;
     this._pointerDirty = true;
+    // The frame pacer (src/pacing.js), the surface's own: a scene's frames
+    // are drawn on a clock of their own, and what one costs — `onDraw` and
+    // the swap, on this thread — is what decides whether the next may
+    // start at once. The policy is this element's `frameRate`, else the
+    // owning window's, read at each request so a change on either follows.
+    this._pacer = new FramePacer();
+    this._ownPolicy = null;
+    this._syncFramePolicy();
   }
 
   get isGlArea() {
     return true;
   }
 
+  /** The policy this surface paces by: its own prop, else the window's. */
+  _framePolicy() {
+    if (this.props.frameRate !== undefined && this.props.frameRate !== null) {
+      return this._ownPolicy;
+    }
+    return this.root?._framePolicy ?? this._pacer.policy;
+  }
+
+  _syncFramePolicy() {
+    const value = this.props.frameRate;
+    this._ownPolicy =
+      value === undefined || value === null
+        ? null
+        : resolveFrameRate(value, '<glarea frameRate>');
+  }
+
   _setRoot(root) {
     super._setRoot(root);
     // the owning window may already exist (a <glarea> mounted into a live
@@ -275,8 +303,21 @@ export class GlAreaNode extends Node {
     this.requestFrame();
   }
 
-  /** Draw one frame on the child window's next frame tick. */
+  /**
+   * Draw one frame on the child window's next frame tick — after whatever
+   * wait the pacer asks for (src/pacing.js). Off by default it answers
+   * "now"; under an adaptive policy a scene whose frames cost more than
+   * their share of the thread is held between them, and a `frameLoop` of
+   * `'always'` becomes a loop at the budget rather than at the display.
+   */
   requestFrame() {
+    if (!this.window || this.destroyed || this._frameScheduled) return;
+    this._pacer.configure(this._framePolicy());
+    if (this._pacer.defer(() => this._requestFrameNow())) return;
+    this._requestFrameNow();
+  }
+
+  _requestFrameNow() {
     if (!this.window || this.destroyed || this._frameScheduled) return;
     this._frameScheduled = true;
     const schedule =
@@ -290,13 +331,28 @@ export class GlAreaNode extends Node {
   }
 
   _drawFrame() {
+    const pacer = this._pacer;
+    pacer.began();
+    let drawn = false;
+    try {
+      drawn = this._drawFrameNow();
+    } finally {
+      pacer.ended(undefined, drawn);
+    }
+    // after the frame is priced, so the loop's next frame is judged by
+    // this one rather than by the one before
+    if (drawn && this.props.frameLoop === 'always') this.requestFrame();
+  }
+
+  /** The frame itself; true when it drew. */
+  _drawFrameNow() {
     const gl = this.gl;
-    if (!gl || this.destroyed) return;
+    if (!gl || this.destroyed) return false;
     const direct = gl.backend === 'direct';
     // On the direct backend every buffer may still be held by the display,
     // and drawing into one before it comes back would paint what is on
     // screen. `onFrameAvailable` asks for this frame again when one frees.
-    if (direct && gl.canRender && !gl.canRender()) return;
+    if (direct && gl.canRender && !gl.canRender()) return false;
     // binds this surface — the GPU context is shared between every <glarea>
     // on the connection — and picks up a resize
     gl.makeCurrent?.();
@@ -325,7 +381,7 @@ export class GlAreaNode extends Node {
     }
     this.props.onDraw?.(gl, info);
     gl.SwapBuffers();
-    if (this.props.frameLoop === 'always') this.requestFrame();
+    return true;
   }
 
   /**
@@ -357,7 +413,9 @@ export class GlAreaNode extends Node {
   }
 
   applyProps(newProps, oldProps) {
+    const before = oldProps ?? this.props;
     super.applyProps(newProps, oldProps);
+    if (newProps.frameRate !== before.frameRate) this._syncFramePolicy();
     // onDraw/clearColor are read at frame time, so any update is a new frame
     this.requestFrame();
   }
@@ -375,6 +433,7 @@ export class GlAreaNode extends Node {
   destroySubtree() {
     if (this.destroyed) return;
     super.destroySubtree();
+    this._pacer.cancel();
     this.gl?.destroy?.();
     this.gl = null;
     this.window?.destroy?.();

package/src/index.d.ts

@@ -9,7 +9,7 @@
 
 import type { ReactNode, RefObject } from 'react';
 import type { DrawnNode, NtkApp, NtkWindow } from './types/nodes.js';
-import type { ReactX11Elements } from './types/elements.js';
+import type { FrameRate, ReactX11Elements } from './types/elements.js';
 
 export * from './types/style.js';
 export * from './types/events.js';
@@ -232,6 +232,15 @@ export interface RootOptions {
    * run each. 6 by default; 0 paints glyphs at every size.
    */
   textStripBelow?: number;
+  /**
+   * How this root's windows pace their frames when their content changes
+   * faster than the display refreshes — the default for every `<window>`
+   * and `<glarea>` that names no `frameRate` of its own. `'display'` (every
+   * frame the clock gives) unless said otherwise; `'adaptive'` holds paints
+   * to a quarter of the time under a flood. `REACT_X11_FRAME_RATE` overrides
+   * it, and the props, from the environment. See {@link FrameRate}.
+   */
+  frameRate?: FrameRate;
   /** `':1'`, `'host:0.0'`, or a unix socket path. Defaults to `$DISPLAY`. */
   display?: string;
   /**