react-x11 2.22.8 → 2.22.10

package/package.json

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

package/src/a11ypace.js

@@ -0,0 +1,83 @@
+// How often an accessibility bridge tells its platform what changed.
+//
+// Both bridges mirror the tree for a platform that reads it on its own
+// schedule: AT-SPI (src/atspi.js) exports objects and sends signals, UI
+// Automation (src/win32/a11y.js) walks a window and pushes a diff. Pushed on
+// every commit, that is paid by everything that commits often, and mostly
+// for nobody. On Windows it was 1.6 ms of each frame of a graph pane's pan
+// (#656). On a Linux desktop whose session runs the AT-SPI bus, as most do
+// with no screen reader in sight, it was a sixth of a 100,000-row table's
+// fling: rows exported, diffed and unexported as they scrolled past.
+//
+// The rule is the one browsers use. Chromium's AXObjectCacheImpl batches
+// non-interactive updates, 150 ms apart once a page has loaded and 350 ms
+// before, and the bounds of anything that is not focused 500 ms apart. It
+// serializes a focus or selection change at once, because that is what the
+// user is waiting on. So here:
+//
+//   - a change after a quiet spell is pushed at once, so a click or a key
+//     that changes one thing is heard immediately;
+//   - a stream of changes (a scroll, a pan, a value ticking) is pushed at
+//     most once per `interval`, and the last push carries the last state;
+//   - what the user is waiting on goes at once regardless: a focus change,
+//     an announcement, and a change to the focused element itself, such as
+//     the characters typed into it. That exception is each bridge's to
+//     call (`urgent`).
+//
+// The interval is 500 ms: at most two pushes a second, the slower end of
+// what Chromium spends. `REACT_X11_A11Y_INTERVAL` sets it in milliseconds,
+// and `0` pushes on every change, as both bridges once did.
+
+export const DEFAULT_A11Y_INTERVAL = 500;
+
+/**
+ * The push interval: `REACT_X11_A11Y_INTERVAL` in milliseconds where it is a
+ * number of them (`0` included), and the default otherwise.
+ */
+export function a11yInterval(env = globalThis.process?.env ?? {}) {
+  const raw = env.REACT_X11_A11Y_INTERVAL;
+  if (raw === undefined || raw === '') return DEFAULT_A11Y_INTERVAL;
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms >= 0 ? ms : DEFAULT_A11Y_INTERVAL;
+}
+
+/**
+ * The pacing, without the pushing: the bridge asks whether a push may go now
+ * and says when one went, and the pacer keeps the one timer a stream owes.
+ */
+export class A11yPacer {
+  constructor(interval = a11yInterval()) {
+    this.interval = interval;
+    this._last = -Infinity;
+    this._timer = null;
+  }
+
+  /**
+   * Something changed. True when it may be pushed now, because nothing has
+   * been pushed for an interval. False when `later` has been set to run once
+   * the interval is up: one timer, however many changes ask while it runs.
+   */
+  ready(later) {
+    if (this._timer) return false;
+    const wait = this._last + this.interval - performance.now();
+    if (wait <= 0) return true;
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      later();
+    }, wait);
+    this._timer.unref?.();
+    return false;
+  }
+
+  /** A push went out, paced or not: the next interval runs from here. */
+  pushed() {
+    this._last = performance.now();
+  }
+
+  /** Drop the push a stream is owed, for one that goes now and takes it. */
+  cancel() {
+    if (this._timer === null) return;
+    clearTimeout(this._timer);
+    this._timer = null;
+  }
+}

package/src/atspi.js

@@ -62,6 +62,7 @@ import {
   diffChars,
 } from './a11y.js';
 import { onApp } from './trace-registry.js';
+import { A11yPacer } from './a11ypace.js';
 import { synthesizeClick } from './events.js';
 import { callHandler } from './errors.js';
 
@@ -100,6 +101,8 @@ const LAYER_WINDOW = 7;
 const ATSPI_VERSION = '2.1';
 
 const EVENT_SIGNATURE = 'siiva{sv}';
+/** D-Bus message type 1: a method call, which is how an AT reads. */
+const METHOD_CALL = 1;
 const CACHE_ITEM_SIGNATURE = '((so)(so)(so)iiassusau)';
 
 // --------------------------------------------------------------------------
@@ -765,7 +768,8 @@ class AtspiBridge {
     this.desktop = [REGISTRY_NAME, ROOT_PATH];
     this.appId = -1;
     this._unsubscribes = [];
-    // batched renderer notifications, flushed per commit / microtask
+    // batched renderer notifications, flushed in a microtask once the pacer
+    // says so (src/a11ypace.js), and at once for what the user waits on
     this._pending = {
       attach: new Set(),
       remove: [],
@@ -775,6 +779,17 @@ class AtspiBridge {
       window: [],
     };
     this._flushScheduled = false;
+    this._pacer = new A11yPacer();
+    /** The focused node, whose own changes are not paced. */
+    this._focused = null;
+    // Pushes are paced, reads are not: whatever the pacer is holding is
+    // flushed before dbus-native dispatches an AT's call, so the objects and
+    // interfaces it asks about exist as the tree has them now. A node React
+    // reused as a slider still exported a button's interfaces until the
+    // next push, and a Value read of it failed.
+    bus.connection?.prependListener?.('message', (msg) => {
+      if (msg.type === METHOD_CALL && this._hasPending()) this.flush();
+    });
   }
 
   // ---- refs and export -------------------------------------------------
@@ -1184,12 +1199,35 @@ class AtspiBridge {
 
   // ---- the queue -------------------------------------------------------
 
+  /**
+   * A change to tell the bus about, when the pacer allows: in this turn's
+   * microtask after a quiet spell, and otherwise once its interval is up,
+   * together with everything else that changed meanwhile. Rows that scroll
+   * in and out between two pushes are then never exported at all: the attach
+   * finds them gone, and the removal finds nothing the AT ever saw.
+   */
   _schedule() {
+    if (this._flushScheduled || this.dead) return;
+    if (this._pacer.ready(() => this.flush())) this._flushSoon();
+  }
+
+  _flushSoon() {
     if (this._flushScheduled || this.dead) return;
     this._flushScheduled = true;
     queueMicrotask(() => this.flush());
   }
 
+  /**
+   * A change the user is waiting to hear: focus moving, or the focused
+   * element's own name, state or text, such as the characters typed into
+   * it. Chromium serializes these at once too. It takes everything pending
+   * with it, so the AT can resolve whatever the event names.
+   */
+  _urgent() {
+    this._pacer.cancel();
+    this._flushSoon();
+  }
+
   /** Is this node under a toplevel the bridge is presenting? Detached
    * subtrees under construction are not, which is what keeps the initial
    * bottom-up build of a tree from queueing one event per node. */
@@ -1214,38 +1252,47 @@ class AtspiBridge {
 
   queueProps(node) {
     this._pending.props.add(node);
-    this._schedule();
+    if (node === this._focused) this._urgent();
+    else this._schedule();
   }
 
   queueText(node) {
     this._pending.text.add(node);
-    this._schedule();
+    if (node === this._focused) this._urgent();
+    else this._schedule();
   }
 
   queueFocus(previous, next) {
     this._pending.focus.push({ previous, next });
-    this._schedule();
+    this._urgent();
   }
 
   queueWindowFocus(win, focused) {
     this._pending.window.push({ win, focused });
-    this._schedule();
+    this._urgent();
+  }
+
+  _hasPending() {
+    const p = this._pending;
+    return (
+      p.attach.size > 0 ||
+      p.remove.length > 0 ||
+      p.props.size > 0 ||
+      p.text.size > 0 ||
+      p.focus.length > 0 ||
+      p.window.length > 0
+    );
   }
 
   flush() {
     if (this.dead) return;
     this._flushScheduled = false;
     const p = this._pending;
-    if (
-      p.attach.size === 0 &&
-      p.remove.length === 0 &&
-      p.props.size === 0 &&
-      p.text.size === 0 &&
-      p.focus.length === 0 &&
-      p.window.length === 0
-    ) {
-      return;
-    }
+    if (!this._hasPending()) return;
+    // this push takes what a stream was owed, and the next interval runs
+    // from here
+    this._pacer.cancel();
+    this._pacer.pushed();
     this._pending = {
       attach: new Set(),
       remove: [],
@@ -1699,8 +1746,15 @@ class AtspiBridge {
       this.queueAttach(child);
     };
     hooks.detach = (parent, child) => {
-      if (!this.exported.has(child) && !this._live(parent)) return;
-      this.queueRemove(parent, child, a11yIndexIn(parent, child));
+      const exported = this.exported.has(child);
+      if (!exported && !this._live(parent)) return;
+      // the index is for the AT's children-changed, which only a child it
+      // saw is owed — and a row scrolled away was usually never exported
+      this.queueRemove(
+        parent,
+        child,
+        exported ? a11yIndexIn(parent, child) : -1,
+      );
     };
     hooks.propsChanged = (node) => {
       if (this.exported.has(node)) this.queueProps(node);
@@ -1720,12 +1774,15 @@ class AtspiBridge {
       if (this.exported.has(node)) this.queueText(node);
     };
     hooks.focus = (previous, next) => {
+      this._focused = next ?? null;
       this.queueFocus(previous, next);
     };
     hooks.windowFocus = (win, focused) => {
       this.queueWindowFocus(win, focused);
     };
-    hooks.commit = () => this.flush();
+    // a commit is one more change to pace, not a push of its own: every
+    // hook above has already asked for the one it needs
+    hooks.commit = () => this._schedule();
     hooks.announce = (text, opts) => {
       // spoken from the active window, which is the context the user is in
       const target =
@@ -1758,6 +1815,7 @@ class AtspiBridge {
   bury() {
     if (this.dead) return;
     this.dead = true;
+    this._pacer.cancel();
     for (const key of Object.keys(hooks)) hooks[key] = null;
     for (const unsubscribe of this._unsubscribes) unsubscribe();
     this._unsubscribes = [];

package/src/cocoa/app.js

@@ -965,6 +965,7 @@ export class CocoaApp {
     // which is more than a display frame when the change costs layout
     // (issue #641). The Wayland backend orders them the same way
     // (`requestSurfaceFrame`).
+    const frames = [];
     const surfaces = [];
     for (const entry of queue) {
       // A window whose last flip has not reached its layer yet (threaded
@@ -993,10 +994,36 @@ export class CocoaApp {
         this._rafQueue.push(entry);
         continue;
       }
-      if (entry.surface) surfaces.push(entry);
-      else runFrame(entry, now);
+      (entry.surface ? surfaces : frames).push(entry);
     }
-    for (const entry of surfaces) runFrame(entry, now);
+    // …and in one commit with them. The overlay and the GL frame are two
+    // layers, each flipped in a transaction of its own — the overlay's in
+    // the window's flush, the GL frame's after its draw — and the draw came
+    // between the two commits: a frame that rebuilt its scene let the
+    // overlay reach the screen a refresh or more before the frame it was
+    // painted for. So a window with a surface drawing in this tick has its
+    // frame and theirs inside one transaction, which puts every layer the
+    // two changed on glass at once; committed with the window's size, as
+    // the frame a worker's resize handshake waits for (`_flip`).
+    const joined = new Set();
+    for (const entry of surfaces) if (entry.wnd) joined.add(entry.wnd);
+    for (const entry of frames) {
+      if (!joined.has(entry.wnd)) runFrame(entry, now);
+    }
+    for (const wnd of joined) {
+      this._native.txBegin({ disableActions: true });
+      try {
+        for (const entry of frames) {
+          if (entry.wnd === wnd) runFrame(entry, now);
+        }
+        for (const entry of surfaces) {
+          if (entry.wnd === wnd) runFrame(entry, now);
+        }
+      } finally {
+        this._native.txCommit(wnd._frameSize?.());
+      }
+    }
+    for (const entry of surfaces) if (!entry.wnd) runFrame(entry, now);
     this._armFrameTimer(soonest, now);
   }
 

package/src/cocoa/bezels.js

@@ -31,8 +31,23 @@
 // 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").
+//
+// ## Taller than one line
+//
+// A push bezel is one height. Asked to fill a taller frame, AppKit draws its
+// own 22pt bezel centred in it — and a `<Button>` whose label wrapped is a
+// taller frame. What AppKit has for that button is the *flexible* push,
+// `NSBezelStyleFlexiblePush`: the same bezel stretched to its frame, the one
+// AppKit gives a title that wraps, and what WebKit and Gecko draw a push
+// button taller than a push button with. At one line the two are the same
+// pixels, the default button's accent aside (the push has a sheen, the
+// flexible one is flat), so a push box keeps its bezel at its own height and
+// is drawn as the flexible push above it (`TALLER`). A bridge that predates
+// the kind keeps the push (`_draws`).
 
 const KINDS = ['push', 'checkbox', 'radio', 'popup', 'slider', 'switch'];
+// what a kind is drawn as in a box taller than its bezel
+const TALLER = Object.freeze({ push: 'flexiblePush' });
 // 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
@@ -55,6 +70,7 @@ export class BezelStore {
     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._drawable = new Map(); // kind → whether the bridge draws it
     this._gen = 0;
     this._MAX = 160;
   }
@@ -118,9 +134,13 @@ export class BezelStore {
    * each scan running the first time it is asked for.
    */
   prefetch(scale) {
+    const kinds = [
+      ...KINDS,
+      ...Object.values(TALLER).filter((kind) => this._draws(kind)),
+    ];
     const jobs = [];
     for (const s of new Set([2, scale])) {
-      for (const kind of KINDS) {
+      for (const kind of kinds) {
         for (const size of SIZES) jobs.push(this._scanLater(kind, size, s));
       }
     }
@@ -132,9 +152,13 @@ export class BezelStore {
    * Returns `{ surface, sx, sy, sw, sh }` — draw with the 9-arg
    * `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.
+   * A push box taller than a push bezel is drawn as the flexible push
+   * ("Taller than one line").
    */
   get(params, w, h, scale, onReady = null) {
     const controlSize = params.controlSize ?? 'regular';
+    const kind = this._kindAt(params.kind, controlSize, h / scale);
+    if (kind !== params.kind) params = { ...params, kind };
     const key = JSON.stringify([
       params.kind,
       controlSize,
@@ -170,6 +194,50 @@ export class BezelStore {
     return frame.entry;
   }
 
+  /** The kind that draws a `kind` box `height` logical px tall: itself, or
+   * above its bezel's own height the kind `TALLER` names for it, where the
+   * bridge draws that. On a worker, before `prefetch`, a kind whose height
+   * is not in yet is itself. */
+  _kindAt(kind, controlSize, height) {
+    const taller = TALLER[kind];
+    if (!taller) return kind;
+    const natural = this.natural(kind, controlSize);
+    if (!natural || height <= natural.height) return kind;
+    return this._draws(taller) ? taller : kind;
+  }
+
+  /**
+   * Whether the bridge draws `kind` at all. One that predates it throws
+   * "unknown control kind" as it reads the parameters — on either thread,
+   * before anything is measured or dispatched — so the question costs one
+   * measure, once. A no keeps the kind it would have replaced, which is a
+   * button whose bezel stops short of its label: broken rather than
+   * degraded, so development hears about it, once.
+   */
+  _draws(kind) {
+    let known = this._drawable.get(kind);
+    if (known !== undefined) return known;
+    try {
+      // off the main thread the callback is how the bridge answers at all;
+      // on it, the call answers in place
+      if (this._answersLater()) this._native.measureControl({ kind }, () => {});
+      else this._native.measureControl({ kind });
+      known = true;
+    } catch {
+      known = false;
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          `react-x11: this @windowkit/appkit has no '${kind}' bezel, so a ` +
+            'native <Button> whose label wrapped is drawn over a one-line ' +
+            'bezel that stops short of it. Update @windowkit/appkit to the ' +
+            'version react-x11 lists in its optionalDependencies.',
+        );
+      }
+    }
+    this._drawable.set(kind, known);
+    return known;
+  }
+
   /** 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) {

package/src/cocoa/window.js

@@ -1013,6 +1013,30 @@ export class CocoaWindow {
     return this.app._requestFrame(cb, this, true);
   }
 
+  /**
+   * Whether a `<glarea>` of this window has a frame queued on its clock —
+   * which keeps this window's frame on the clock too, where the early frame
+   * an input asks for would have painted it at once (src/frames.js).
+   *
+   * The clock pairs the two: a tick runs this window's frame and then its
+   * surfaces', so a GL frame goes out after the overlay its children were
+   * painted on (#641). An input painted early went around that — the
+   * window's frame, the overlay with it and the present, inside the input's
+   * own dispatch, and the GL frame the same input asked for a refresh or
+   * more later, on the clock. For that long the children were drawn over
+   * the frame before: a graph whose cards were a surface's children hid
+   * them for a wheel zoom that way, and showed its edges with nothing under
+   * them for 20–25ms, until the GL frame that drew the cards came. Such an
+   * input is answered on the clock, both halves in order. What it gives up
+   * is its 2D half's head start; the GL half never had one.
+   */
+  surfaceFrameOwed() {
+    for (const entry of this.app._rafQueue) {
+      if (entry.surface && entry.wnd === this) return true;
+    }
+    return false;
+  }
+
   /**
    * The earliest moment this window's clock will hand out another frame,
    * for a gate of `interval` ms — the display's period by default, which

package/src/components/Button.js

@@ -8,11 +8,11 @@ import {
   ABS_FILL,
   Bezel,
   NATIVE_BAND,
+  NATIVE_FOOTPRINT,
   NATIVE_RING,
-  TITLE_BASELINE,
   bezelNatural,
   bezelShadow,
-  nativeFootprintStyle,
+  nativeTitleMargins,
   nativeTitleStyle,
   pressWash,
   useNativeControls,
@@ -24,6 +24,11 @@ const h = React.createElement;
 const VARIANTS = ['solid', 'outline', 'ghost'];
 const SIZES = ['medium', 'small'];
 
+// A label squeezed below its width wraps at its words, and the lines are
+// centred under one another, as AppKit centres a title that wrapped and a
+// browser a `<button>`'s. One line is as wide as its box, so it is not moved.
+const CENTRED_LINES = Object.freeze({ textAlign: 'center' });
+
 /**
  * <Button onPress variant size primary disabled …boxProps>label</Button> —
  * the standard push button the examples kept re-implementing: hover/press/
@@ -97,8 +102,8 @@ export function Button({
       {
         theme,
         // The footprint the caller's style sizes; the button below keeps
-        // AppKit's height inside it, centred (`nativeFootprintStyle`).
-        style: [nativeFootprintStyle(nat), style],
+        // its own height inside it, centred (`NATIVE_FOOTPRINT`).
+        style: [NATIVE_FOOTPRINT, style],
       },
       h(
         'box',
@@ -117,16 +122,23 @@ export function Button({
               gap: small ? 6 : 8,
               // AppKit's metrics, not the palette's: a native bezel is
               // designed at its own height, and stretching it is what this
-              // mode exists to avoid. Width still follows the label.
-              height: nat.height,
+              // mode exists to avoid. Width still follows the label — and
+              // so does the height, once there is not the width for the
+              // label: it wraps at its words, as a drawn one does, and the
+              // lines it grew by make the control taller. AppKit has a
+              // bezel for that button (src/cocoa/bezels.js); a title
+              // pinned to one line's height put its first line above the
+              // bezel instead.
+              minHeight: nat.height,
               paddingLeft: small ? 10 : 14,
               paddingRight: small ? 10 : 14,
               // The natural box is the bezel's footprint, shadow included;
-              // the body is what the title is placed against — and placed,
-              // not centred (`TITLE_BASELINE`). A label centred by its
-              // capitals sat 1pt low beside a native button.
+              // inside the shadow is the body, which an icon is centred on
+              // and the title is placed against — placed, not centred
+              // (`nativeTitleMargins`). A label centred by its capitals sat
+              // 1pt low beside a native button.
               paddingTop: shadow.top,
-              paddingBottom: shadow.bottom + TITLE_BASELINE[controlSize],
+              paddingBottom: shadow.bottom,
               // The keyboard ring is the renderer's, on this box — shaped by
               // the bezel's corners and hugging it, as AppKit's is
               // (`NATIVE_RING`), rather than the palette's offset rectangle.
@@ -151,7 +163,11 @@ export function Button({
           isDefault: primary && !disabled,
           style: ABS_FILL,
         }),
-        labelContent(children ?? label, nativeTitleStyle(controlSize)),
+        labelContent(children ?? label, [
+          nativeTitleStyle(controlSize),
+          nativeTitleMargins(nat, shadow, controlSize),
+          CENTRED_LINES,
+        ]),
         // The press answer. Last child on purpose: `:active` marks the
         // pressed node and its ancestors, and the topmost child is what the
         // press lands on. No hover tint — AppKit buttons have none.
@@ -271,6 +287,6 @@ export function Button({
         style,
       ],
     },
-    labelContent(children ?? label),
+    labelContent(children ?? label, CENTRED_LINES),
   );
 }

package/src/components/Select.js

@@ -10,12 +10,12 @@ import {
   ABS_FILL,
   Bezel,
   NATIVE_BAND,
+  NATIVE_FOOTPRINT,
   NATIVE_MENU,
   NATIVE_RING,
   TITLE_BASELINE,
   bezelNatural,
   bezelShadow,
-  nativeFootprintStyle,
   nativeTitleStyle,
   pressWash,
   useNativeControls,
@@ -550,7 +550,7 @@ export function Select({
           },
         // The caller's style, on the trigger where the trigger is the whole
         // control. Under a native bezel it sizes the footprint below instead
-        // and the trigger keeps AppKit's height (`nativeFootprintStyle`).
+        // and the trigger keeps AppKit's height (`NATIVE_FOOTPRINT`).
         !nativeControls && style,
       ],
     },
@@ -677,6 +677,6 @@ export function Select({
   // around them is what a `height`, a `flexGrow` or a parent's align-stretch
   // is free to make taller, with the control centred in it (issue #510).
   return nativeControls
-    ? h('box', { theme, style: [nativeFootprintStyle(nat), style] }, trigger)
+    ? h('box', { theme, style: [NATIVE_FOOTPRINT, style] }, trigger)
     : trigger;
 }