react-x11 2.7.0 → 2.8.1

package/src/cocoa/window.js

@@ -9,6 +9,7 @@
 import { CocoaContext2D } from './context2d.js';
 import { CocoaDropTransport, dragSpec } from './dnd.js';
 import { CocoaLayerPresenter } from './presenter.js';
+import { CocoaPromotion } from './promotion.js';
 
 let nextWindowId = 1;
 
@@ -110,6 +111,22 @@ export class CocoaWindow {
         this._presenter.animate(node, prop, entry);
       this.cancelNodeAnimation = (node, prop) =>
         this._presenter.cancel(node, prop);
+    } else if (app._promote) {
+      // Layer promotion (src/cocoa/promotion.js): the surface presenter
+      // keeps the frame, and the nodes that animate get a layer of their
+      // own above it. The same two animation hooks as layers mode; the
+      // invalidate channel, for what the promoted rasters repaint; and the
+      // frame's word in before the paint, where a node is moved onto or off
+      // its layer and the bitmap under it claimed in the same frame.
+      this._promotion = new CocoaPromotion(this);
+      this.animateNode = (node, prop, entry) =>
+        this._promotion.animate(node, prop, entry);
+      this.cancelNodeAnimation = (node, prop) =>
+        this._promotion.cancel(node, prop);
+      this.noteInvalidate = (damage, layoutChanged) =>
+        this._promotion.noteInvalidate(damage, layoutChanged);
+      this.prepareFrame = (root, layoutRan) =>
+        this._promotion.frame(root, layoutRan);
     }
     app._registerWindow(this);
   }
@@ -224,6 +241,7 @@ export class CocoaWindow {
       this.app.cancelAttention(this._attentionRequest);
       this._attentionRequest = null;
     }
+    this._promotion?.destroy();
     this._native.destroyWindow2(this._h);
     this._releaseBacking();
   }
@@ -312,13 +330,23 @@ export class CocoaWindow {
    * The source side: hand a DragSession's gesture to an NSDraggingSession
    * (see src/cocoa/dnd.js for what the spec carries). Returns at once; the
    * session reports back as `drag-session-*` events.
+   *
+   * And the pump stops here. AppKit tracks the gesture on this thread, so
+   * `pump2` does not return until the drop and no timer of ours runs in
+   * between — the frame that shows the drag has begun (a `<popup
+   * dragPreview>` mounted by `onDragStart`, a source dimmed by
+   * `:dragging`) has to go out on the way past. Motion is otherwise paced
+   * on the frame clock and not flushed per event (`_routeMotion`); this is
+   * the one motion whose answer has no next tick to wait for.
    */
   beginDrag(session) {
     if (this.destroyed) return null;
-    return this._native.beginDrag(
+    const began = this._native.beginDrag(
       this._h,
       dragSpec(session, this._native, this.scale),
     );
+    this.app._afterInput();
+    return began;
   }
 
   setTransientFor() {

package/src/dnd.js

@@ -258,6 +258,13 @@ export class DropSession {
     // FIFO gate: messages queue behind atom interning and XdndEnter's
     // async type-list resolution, so a Position never overtakes its Enter.
     this._chain = Promise.resolve();
+    // The lane an enter/over dispatch schedules its renders in. Continuous
+    // by default, because a drag hovering is a stream like the pointer's
+    // own and the frame clock paces it. A transport whose backend *stops*
+    // that clock for the duration of the drag raises it — the cocoa one
+    // does (src/cocoa/dnd.js), because inside AppKit's tracking loop a
+    // render scheduled for the next frame lands after the drop.
+    this.hoverPriority = ContinuousEventPriority;
     this._reset();
   }
 
@@ -470,7 +477,7 @@ export class DropSession {
       action: this.requestedAction,
       freeze: false,
     };
-    runWithPriority(ContinuousEventPriority, () => {
+    runWithPriority(this.hoverPriority, () => {
       this._updateDragPath(path, native);
       // onDragOver may override the declarative answer, synchronously —
       // same latency budget as any event handler, no render awaited
@@ -1258,20 +1265,6 @@ export class DragSession {
       Array.isArray(actions) && actions.length > 0 ? actions : ['copy'];
     this.currentAction = this.actions[0];
     this._resolved = new Map();
-    const ev = this.node.events.dispatch('DragStart', source, native, {
-      types: this.types,
-      action: this.currentAction,
-      source: 'internal',
-      screenX: (native.rootx ?? native.x) / this.node.events.scale,
-      screenY: (native.rooty ?? native.y) / this.node.events.scale,
-    });
-    if (ev.defaultPrevented) {
-      this._reset();
-      return false;
-    }
-    this.phase = 'dragging';
-    source.setStyleState(':dragging', true);
-    this._setCursor('grab');
     // A backend with a drag session of its own (the cocoa backend's
     // NSDraggingSession, src/cocoa/dnd.js) takes the gesture from here:
     // the pointer's motion and release stop arriving and come back as
@@ -1279,7 +1272,34 @@ export class DragSession {
     // comes through that window's destination events, routed to this
     // session's live payload by `app._activeDrag`.
     const wnd = this.node.window;
-    if (typeof wnd?.beginDrag === 'function') {
+    const nativeSession = typeof wnd?.beginDrag === 'function';
+    // …and it owns the thread for the *whole* gesture, so anything this
+    // dispatch schedules for later has no later: the `<popup dragPreview>`
+    // an `onDragStart` setState renders would otherwise be created after
+    // the drop. Discrete priority puts the update in the one lane a
+    // backend can land by hand from inside a callback (`flushSyncWork`,
+    // src/cocoa/app.js `_afterInput`). Where the frame clock keeps running,
+    // the motion this arrived on is paced like any other and the update
+    // keeps the priority the dispatcher gave it.
+    const startEvent = () =>
+      this.node.events.dispatch('DragStart', source, native, {
+        types: this.types,
+        action: this.currentAction,
+        source: 'internal',
+        screenX: (native.rootx ?? native.x) / this.node.events.scale,
+        screenY: (native.rooty ?? native.y) / this.node.events.scale,
+      });
+    const ev = nativeSession
+      ? runWithPriority(DiscreteEventPriority, startEvent)
+      : startEvent();
+    if (ev.defaultPrevented) {
+      this._reset();
+      return false;
+    }
+    this.phase = 'dragging';
+    source.setStyleState(':dragging', true);
+    this._setCursor('grab');
+    if (nativeSession) {
       this._nativeSession = true;
       this.app._activeDrag = this;
       try {
@@ -1295,7 +1315,12 @@ export class DragSession {
   }
 
   /** `drag-session-moved` on a native session: the source's `onDrag`, in
-   * global device pixels, with whether a window of ours has accepted. */
+   * global device pixels, with whether a window of ours has accepted.
+   *
+   * Discrete priority, like the start: this is the only news of the gesture
+   * that arrives while the native session owns the thread, so the render it
+   * schedules has to be landable from inside the callback. A preview that
+   * follows the pointer is exactly a render per position. */
   nativeMoved(ev) {
     if (this.phase !== 'dragging' || !this._nativeSession) return;
     const s = this.node.scale;
@@ -1312,18 +1337,20 @@ export class DragSession {
     };
     const source = this.source;
     if (source && !source.destroyed && source.props.onDrag) {
-      callHandler(
-        source,
-        'onDrag',
-        source.props.onDrag,
-        this.node.events._makeEvent('drag', native, source, {
-          types: this.types,
-          action: this.currentAction,
-          source: this.localSession ? 'internal' : 'external',
-          accepted: this.accepted,
-          screenX: rootX / this.node.events.scale,
-          screenY: rootY / this.node.events.scale,
-        }),
+      runWithPriority(DiscreteEventPriority, () =>
+        callHandler(
+          source,
+          'onDrag',
+          source.props.onDrag,
+          this.node.events._makeEvent('drag', native, source, {
+            types: this.types,
+            action: this.currentAction,
+            source: this.localSession ? 'internal' : 'external',
+            accepted: this.accepted,
+            screenX: rootX / this.node.events.scale,
+            screenY: rootY / this.node.events.scale,
+          }),
+        ),
       );
     }
   }
@@ -1343,10 +1370,20 @@ export class DragSession {
     const rootY = Math.round((ev.y ?? 0) * s);
     const operation =
       ev.operation && ev.operation !== 'none' ? ev.operation : null;
-    this._end(
-      { x: rootX - origin.x, y: rootY - origin.y, rootx: rootX, rooty: rootY },
-      ev.dropped ? operation : null,
-      Boolean(ev.dropped),
+    // the release, and the last callback before the thread comes back:
+    // `onDragEnd` takes the preview down, and that is a discrete answer to
+    // the button like any other
+    runWithPriority(DiscreteEventPriority, () =>
+      this._end(
+        {
+          x: rootX - origin.x,
+          y: rootY - origin.y,
+          rootx: rootX,
+          rooty: rootY,
+        },
+        ev.dropped ? operation : null,
+        Boolean(ev.dropped),
+      ),
     );
   }
 

package/src/index.d.ts

@@ -188,7 +188,17 @@ export interface RootOptions {
    * 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).
+   * CALayer per drawn node, opt-in while it is measured). `promote` is the
+   * surface presenter's layer promotion: a plain `<box>` with a transition
+   * or a loop on its colour, border or radius gets a CALayer of its own
+   * above the bitmap for as long as it animates, and the render server
+   * draws the motion — no frames, and it keeps moving while the JS thread
+   * is busy. On by default where the bridge draws a layer's colour and a
+   * rastered one alike (`@windowkit/appkit` >= 0.5.1, which says so with
+   * `colorSpace()`; off on 0.5.0, where the two shades differed); `true`
+   * turns it on regardless, `false` keeps every animation on the frame
+   * clock.
+   * `REACT_X11_COCOA_PROMOTE=1` / `=0` say the same from the environment.
    * `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
@@ -208,6 +218,7 @@ export interface RootOptions {
    */
   cocoa?: {
     presenter?: 'surface' | 'layers';
+    promote?: boolean;
     frameInterval?: number;
     pumpInterval?: number;
     appName?: string;

package/src/nodes.js

@@ -1913,6 +1913,10 @@ export class Node {
     this._floorMeasureMode = null;
     this.root = null; // owning WindowNode once attached
     this.hidden = false;
+    // Composited on a layer of its own above the window's bitmap, by a
+    // presenter that can (src/cocoa/promotion.js): the paint walk leaves a
+    // hole where it is, and the presenter draws it — the `<glarea>` idiom.
+    this._promoted = false;
     this.destroyed = false;
     // absolute rect within the owning window, filled by absolutize()
     this.abs = { x: 0, y: 0, width: 0, height: 0 };
@@ -2285,10 +2289,11 @@ export class Node {
 
   // --- the presenter's half of an animation ---------------------------------
   //
-  // Three feature-detected hooks on the window (src/cocoa/window.js, layers
-  // mode only): `animateNode(node, prop, entry)` answers true when the
-  // presenter will run the entry itself, `cancelNodeAnimation(node, prop)`
-  // stops what it runs for the property, and the presenter calls back
+  // Two feature-detected hooks on the window (src/cocoa/window.js: the
+  // layer presenter, and the surface presenter's layer promotion —
+  // src/cocoa/promotion.js): `animateNode(node, prop, entry)` answers true
+  // when the presenter will run the entry itself, `cancelNodeAnimation(node,
+  // prop)` stops what it runs for the property, and the presenter calls back
   // through `_offloadEnded` / `_offloadDeclined` below. An entry the
   // presenter took is `offloaded`: it stays in `_anim` — so a retarget, a
   // loop-stop rule and `sameAnimation` all see it — but it contributes no
@@ -5315,6 +5320,7 @@ export class Node {
       ctx.clip();
     }
     for (const child of order) {
+      if (child._promoted) continue; // on a layer of its own: a hole here
       if (child._offscreen()) continue;
       if (child._outsideDamage()) continue;
       child.paint(ctx);
@@ -10467,8 +10473,18 @@ export class WindowNode extends Scrollable(Node) {
    * and advertising lazily would race sources that cache the window list
    * at drag start. A window with no registered drop targets answers "not
    * accepting" once per entry instead (DropSession).
+   *
+   * The one exception is a `<popup dragPreview>`. It follows the pointer,
+   * so for the whole gesture it is the frontmost window under it, and it
+   * must never be what the drag is over. Where react-x11 picks the target
+   * itself (src/dnd.js `topLevelAt`) it is skipped by name; where the OS
+   * picks — AppKit routes a drag to the frontmost window registered for a
+   * type it carries, and looks past one that registered none — the only
+   * way to say so is to register nothing (#488). So a preview gets none of
+   * this: no session, no registry entry, no property.
    */
   _initDnd() {
+    if (this.props.dragPreview) return;
     const wnd = this.window;
     const X = this.app?.X;
     // A backend with drop machinery of its own (the cocoa backend's
@@ -11552,6 +11568,13 @@ export class WindowNode extends Scrollable(Node) {
       watchDesktopSettings(this.app, () => this._refreshLoops()),
     ];
     this._loopVisibilityChanged();
+    // The window has a presenter now, which it did not when a loop declared
+    // at mount started on the clock (`_setRoot` runs before `realize`):
+    // every loop is asked again here, so one a presenter can take moves
+    // over on the window's first frame rather than at the next swap that
+    // happens to re-resolve its style. Where nothing can take it, the
+    // second look at an unchanged declaration is a no-op.
+    this._refreshLoops();
   }
 
   _unwatchLoops() {
@@ -11725,8 +11748,19 @@ export class WindowNode extends Scrollable(Node) {
     // A retained presenter keeps a per-node diff instead of damage rects,
     // and this is the one channel every change already announces itself on
     // (docs/macos.md §"One renderer, two presenters"). Feature-detected: an
-    // ntk window has no ear here and the X11 path is byte-identical.
-    this.window?.noteInvalidate?.(damage, layoutChanged, reason);
+    // ntk window has no ear here and the X11 path is byte-identical. A
+    // presenter that answers `true` has taken the claim onto a layer of its
+    // own (src/cocoa/promotion.js): the bitmap owes nothing for it, and the
+    // frame that is still owed — for the presenter's half, `prepareFrame` —
+    // paints nothing unless something else claims.
+    const taken =
+      this.window?.noteInvalidate?.(damage, layoutChanged, reason) === true;
+    if (taken && !layoutChanged) {
+      this._damage ??= [];
+      this.needsPaint = true;
+      this._scheduleFrame();
+      return;
+    }
     if (layoutChanged) {
       this.needsLayout = true;
       // The content floors are measured from the tree, so anything that
@@ -11832,6 +11866,11 @@ export class WindowNode extends Scrollable(Node) {
       this._damage = addDamageRect(this._damage, bounds, this._damageRectCap());
     }
     this.needsPaint = true;
+    this._scheduleFrame();
+  }
+
+  /** A frame, on the window's clock. */
+  _scheduleFrame() {
     // Recorded before the `_scheduled` gate, not inside it: the debt is
     // "this window has damage", which a discrete event may pay off early
     // (see frames.js). Tying it to whether a callback is outstanding would
@@ -11959,6 +11998,13 @@ export class WindowNode extends Scrollable(Node) {
       for (const node of this._reflowed) node._reflowBefore = null;
       this._reflowed.clear();
     }
+    // A presenter compositing part of the tree on layers of its own — the
+    // surface presenter's promoted nodes (src/cocoa/promotion.js) — gets
+    // its word in here: after layout, so it sees where everything landed,
+    // and before the damage is taken, so a node it moves onto or off a
+    // layer claims the bitmap under it in this very frame. Feature-detected
+    // like `presentFrame`; an ntk window has no such half.
+    this.window.prepareFrame?.(this, layoutRan);
     // any node this pass laid out may be what an open popup is anchored to
     if (layoutRan) this._notifyAnchorChange();
     // after layout (the claims above included), before the damage is taken:
@@ -12504,6 +12550,11 @@ export class WindowNode extends Scrollable(Node) {
           if (!check(child)) return false;
           continue;
         }
+        // A node on a layer of its own (src/cocoa/promotion.js) has no
+        // pixels in the bitmap the band is cut from, so nothing of it can
+        // be dragged along — a pulsing toast over a list is what promotion
+        // is for, and this is the half of it that keeps the pan a blit.
+        if (child._promoted) continue;
         if (rectsOverlap(child._subtreeBounds(), vp)) return false;
       }
       return true;
@@ -12706,6 +12757,14 @@ export class WindowNode extends Scrollable(Node) {
       this._lastReasons = EMPTY_REASONS;
     }
     if (damage === FULL_DAMAGE || !damage) return null;
+    // an empty list: every claim this frame made was answered on a layer of
+    // its own (`invalidate`, the presenter's `true`), and the bitmap paints
+    // nothing — which is not the same as nothing having been claimed
+    if (damage.length === 0) {
+      this._lastDamageRects = [];
+      this._lastDamage = { x: 0, y: 0, width: 0, height: 0 };
+      return [];
+    }
     const rects = [];
     for (const claimed of damage) {
       const clamped = this._clampDamage(claimed, width, height);

package/src/types/elements.d.ts

@@ -436,8 +436,11 @@ export interface WindowProps
   xi2?: boolean | 'auto';
   /**
    * Mark this window as a drag preview: the drag router never treats it as
-   * the window under the pointer, so a `<popup dragPreview>` can follow the
-   * pointer without swallowing its own drag. See `useDragSource`.
+   * the window under the pointer, and it is never a drop destination — on
+   * the cocoa backend, where AppKit picks the destination, that is what
+   * lets a drop reach the window beneath it. A `<popup dragPreview>` can
+   * therefore follow the pointer without swallowing its own drag. Read when
+   * the window is created. See `useDragSource`.
    */
   dragPreview?: boolean;
   /**