react-x11 2.6.1 → 2.8.0

package/src/nodes.js

@@ -32,14 +32,17 @@ import {
   isLayoutProp,
   styleUsesTokens,
   resolveTokens,
-  styleHasSizeQueries,
-  styleHasSupportsQueries,
+  queryKinds,
+  QUERY_SIZE,
+  QUERY_SUPPORTS,
+  QUERY_CONTAINER,
+  containerQueryNames,
+  containerAnswers,
   resolveQueries,
   DEFAULT_FOCUS_RING,
   resolveHitSlop,
   resolveBorderWidths,
   resolveBorderColors,
-  tint,
 } from './styles.js';
 import {
   blurKernel,
@@ -83,6 +86,7 @@ import {
   registerTopLevel,
   XDND_VERSION,
 } from './dnd.js';
+import { TYPE_GROUPS } from './transfer.js';
 import { addPendingFrame, clearPendingFrame } from './frames.js';
 import { createClientMessages } from './clientmessage.js';
 import {
@@ -671,6 +675,11 @@ export function appearanceChanged(app) {
   // started here would reach the connection a tick after it closed and throw
   // out of the frame clock, where nothing is waiting to catch it.
   if (!app || app.X?._closing) return;
+  // A backend that renders native control bezels caches them by every
+  // parameter that changes the pixels — except the desktop's accent, which
+  // the toolkit reads for itself. The repaint below would blit the old
+  // colour back out of that cache, so it is forgotten first.
+  app.nativeBezels?.clear?.();
   for (const node of app._rootChildren ?? []) {
     if (node.destroyed) continue;
     node._themeChanged();
@@ -718,6 +727,22 @@ function shadowExtentOf(style, scale = 1) {
 
 const DEV = process.env.NODE_ENV !== 'production';
 
+/** How many extra layout passes a flush spends settling `@container` blocks
+ *  before it takes the layout it has — see `_settleContainerQueries`. */
+const CONTAINER_QUERY_PASSES = 3;
+
+/** The sizes a node's container blocks were resolved against, as one
+ *  comparable string — what a pinned node is held at. */
+function containersKey(containers) {
+  if (!containers) return '';
+  let key = '';
+  for (const name of Object.keys(containers)) {
+    const c = containers[name];
+    key += `${name}:${c.width}x${c.height};`;
+  }
+  return key;
+}
+
 // Connections already told they have no 32-bit visual (`_argbAttributes`).
 const warnedNoArgb = new WeakSet();
 
@@ -1888,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 };
@@ -1937,6 +1966,13 @@ export class Node {
     // `null` is "commitMount is still to come", `false` is "it has been and
     // gone", and an Error is one waiting for it
     this._tokenError = null;
+    // `'@container …'` blocks (styles.js), on the nodes that carry them and
+    // null on every other node: the style the record was built for, the
+    // container names it asks about (`''` for the unnamed ones), the sizes
+    // and answers the blocks last resolved to, and the pin an oscillating
+    // design is held at — see WindowNode._resolveContainerQueries. Before
+    // `_syncStyle`, which reads and writes it.
+    this._cq = null;
     this._syncStyle(props);
     this.yoga = yoga ? createLayoutNode() : null;
     if (this.yoga) {
@@ -1993,7 +2029,8 @@ export class Node {
     this.states[':disabled'] = Boolean(props.disabled);
     // window size queries fold into the base before state blocks, so a
     // `:hover` inside the wide layout still wins over the wide layout
-    const queried = styleHasSizeQueries(this._baseStyle);
+    const kinds = queryKinds(this._baseStyle);
+    const queried = (kinds & QUERY_SIZE) !== 0;
     if (queried !== this._queried) {
       this._queried = queried;
       const root = this.root;
@@ -2009,7 +2046,7 @@ export class Node {
     // assigned, so the first pass has nowhere to register and a "did it
     // change" guard would keep it unregistered forever. Set.add is
     // idempotent and these blocks are rare.
-    const asks = styleHasSupportsQueries(this._baseStyle);
+    const asks = (kinds & QUERY_SUPPORTS) !== 0;
     this._supportsQueried = asks;
     if (this.root?._supportsQueryNodes) {
       if (asks) this.root._supportsQueryNodes.add(this);
@@ -2029,13 +2066,53 @@ export class Node {
       if (wantsAttention) this.root._attentionNodes.add(this);
       else this.root._attentionNodes.delete(this);
     }
-    if (queried || asks) {
+    // `@container` blocks keep a third registry: what re-resolves them is a
+    // layout pass moving the container they ask about — neither a resize
+    // nor the server's answer. The record exists only on the nodes that
+    // ask, so every other node pays one bit test here and nothing below.
+    // Insertion registers through `_registerSizeQueries`; this is for a
+    // style that starts or stops asking on a node already in a window.
+    const asksContainers = (kinds & QUERY_CONTAINER) !== 0;
+    let containers = null;
+    if (asksContainers) {
+      const base = this._baseStyle;
+      let cq = this._cq;
+      if (cq === null || cq.style !== base) {
+        if (cq === null) {
+          cq = this._cq = {
+            style: base,
+            names: null,
+            containers: null,
+            answers: '',
+            pin: null,
+            warned: false,
+          };
+        } else {
+          // a different style asks different questions, and a pin held for
+          // the old one is not an answer to the new one
+          cq.style = base;
+          cq.pin = null;
+        }
+        cq.names = containerQueryNames(base);
+      }
+      this.root?._containerQueryNodes?.add(this);
+      containers = this._pinnedContainerSizes();
+    } else if (this._cq !== null) {
+      this._cq = null;
+      this.root?._containerQueryNodes?.delete(this);
+    }
+    if (queried || asks || asksContainers) {
       this._baseStyle = resolveQueries(this._baseStyle, {
         size: this.root?.querySize ?? null,
         // null before the window is realized, which reads as "not
         // supported" — the fallback design is the one that works everywhere
         supports: this.root?.capabilities ?? null,
+        containers,
       });
+      if (asksContainers) {
+        this._cq.containers = containers;
+        this._cq.answers = containerAnswers(this._baseStyle, containers);
+      }
     }
     this._stateful = hasStateStyles(this._baseStyle);
     // The scale multiplies *after* every merge — state blocks, queries,
@@ -2085,7 +2162,7 @@ export class Node {
         const duration = transitionFor(target, prop);
         if (duration <= 0) continue;
         if (interpolate(from, to, 0.5) === null) continue; // no midpoint: snap
-        (this._anim ??= new Map()).set(prop, {
+        const entry = {
           from,
           to,
           duration,
@@ -2094,8 +2171,23 @@ export class Node {
           // be seconds old — and the first tick would then find the
           // transition already over and jump straight to the end
           start: now(),
-        });
-        this.root?._startAnimating(this);
+        };
+        const previous = this._anim?.get(prop);
+        (this._anim ??= new Map()).set(prop, entry);
+        // A presenter that can run it in the render server takes it here:
+        // the node's style then goes straight to the target — the layer's
+        // model value — and the one frame that sends it carries the
+        // animation with it (src/cocoa/presenter.js). Declined, or with no
+        // such presenter, the window's frame clock runs it as it always has.
+        if (this._offload(prop, entry)) {
+          entry.offloaded = true;
+          this.root?.invalidate(false, damageForAnimation(this), 'animation');
+        } else {
+          // …and one the presenter had must not keep running underneath the
+          // values the clock is about to write
+          if (previous?.offloaded) this._cancelOffload(prop, previous);
+          this.root?._startAnimating(this);
+        }
       }
     }
     // After the transitions, before the style is assembled: a loop that just
@@ -2187,10 +2279,78 @@ export class Node {
 
   _animatedValues() {
     const values = {};
-    for (const [prop, a] of this._anim) values[prop] = a.value ?? a.from;
+    for (const [prop, a] of this._anim) {
+      // an offloaded property shows its target: the render server draws the
+      // motion over the model value, and the model is the style
+      if (!a.offloaded) values[prop] = a.value ?? a.from;
+    }
     return values;
   }
 
+  // --- the presenter's half of an animation ---------------------------------
+  //
+  // 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
+  // value to the style, is skipped by the tick, and keeps the node out of the
+  // window's animating set. The X11 path has none of these hooks and is
+  // byte-identical (docs/architecture/animation.md §4).
+
+  _offload(prop, entry) {
+    const wnd = this.root?.window;
+    if (typeof wnd?.animateNode !== 'function') return false;
+    return wnd.animateNode(this, prop, entry) === true;
+  }
+
+  _cancelOffload(prop, entry) {
+    if (!entry?.offloaded) return;
+    this.root?.window?.cancelNodeAnimation?.(this, prop);
+  }
+
+  /** The presenter is done with `entry` — it ran out, or its layer went.
+   *  A transition is over either way (the model is the target). A loop
+   *  never ends on its own, so a loop that comes back this way lost its
+   *  layer, and the frame clock takes it over rather than letting it stop. */
+  _offloadEnded(prop, entry) {
+    if (this._anim?.get(prop) !== entry) return;
+    if (entry.loop && !this.destroyed) {
+      this._offloadDeclined(prop, entry);
+      return;
+    }
+    this._anim.delete(prop);
+    if (!this._anim.size) this.root?._animating.delete(this);
+  }
+
+  /** The presenter could not run `entry` after all — the node turned into a
+   *  raster between the swap and the frame. The frame clock takes it from
+   *  the top; the property's declared start is where the pixels still are. */
+  _offloadDeclined(prop, entry) {
+    if (this._anim?.get(prop) !== entry || this.destroyed) return;
+    entry.offloaded = false;
+    entry.start = now();
+    this.style = { ...this._targetStyle, ...this._animatedValues() };
+    this.root?._startAnimating(this);
+  }
+
+  /** Keep the frame clock running only for what the clock itself animates;
+   *  an offloaded-only node needs one frame — the one that sends the model
+   *  and the animation — and not a loop of them. */
+  _scheduleAnimationFrames() {
+    for (const a of this._anim?.values() ?? []) {
+      if (!a.offloaded) {
+        this.root?._startAnimating(this);
+        return;
+      }
+    }
+    this.root?._animating.delete(this);
+    this.root?.invalidate(false, damageForAnimation(this), 'animation');
+  }
+
   /**
    * The style declared a set of loops (`animation`, styles.js): remember
    * them and reconcile what is running against them.
@@ -2237,6 +2397,7 @@ export class Node {
         if (!a.loop) continue;
         if (running && specs.some((spec) => spec.prop === prop)) continue;
         anim.delete(prop);
+        this._cancelOffload(prop, a);
         changed = true;
         if (isLayoutProp(prop)) layoutTouched = true;
       }
@@ -2249,13 +2410,28 @@ export class Node {
         // spinner that jumps back to the start whenever anything above it
         // re-rendered — which is the frame after every state change in the
         // app.
-        if (current?.loop && sameAnimation(current, spec)) continue;
-        (this._anim ??= new Map()).set(spec.prop, {
+        if (current?.loop && sameAnimation(current, spec)) {
+          // A loop the clock started before the window had a presenter —
+          // one declared at mount runs from `_setRoot`, before `realize` —
+          // moves over the first time a presenter can take it. Its phase is
+          // the render server's from here, which is what a restart costs.
+          if (!current.offloaded && this._offload(spec.prop, current)) {
+            current.offloaded = true;
+            changed = true;
+          }
+          continue;
+        }
+        // a changed declaration, or a transition the loop takes over from:
+        // whatever the presenter ran for the property stops first
+        if (current?.offloaded) this._cancelOffload(spec.prop, current);
+        const entry = {
           ...spec,
           loop: true,
           start: now(),
           value: animationValueAt(spec, 0),
-        });
+        };
+        (this._anim ??= new Map()).set(spec.prop, entry);
+        if (this._offload(spec.prop, entry)) entry.offloaded = true;
         changed = true;
         if (isLayoutProp(spec.prop)) layoutTouched = true;
       }
@@ -2269,7 +2445,7 @@ export class Node {
     // a stop has to leave the frame clock idle, and a tick is exactly what
     // there may never be another of.
     if (!this._anim?.size) this.root?._animating.delete(this);
-    if (running) this.root?._startAnimating(this);
+    if (running) this._scheduleAnimationFrames();
     if (!write) return true;
     if (layoutTouched && this.yoga) {
       applyLayoutStyle(this.yoga, this.style, before);
@@ -2316,19 +2492,23 @@ export class Node {
   _tickAnimations(now) {
     if (!this._anim?.size) return false;
     let layoutChanged = false;
+    let ticking = 0; // entries the clock runs, as against the presenter's
     const before = this.style;
     for (const [prop, a] of this._anim) {
+      if (a.offloaded) continue;
       if (a.loop) {
         // No end to test for and no rounding to accumulate: the phase is a
         // modulo of the elapsed time, so a bar that has been going for an
         // hour is exactly where the clock says.
         a.value = animationValueAt(a, now - a.start);
         if (isLayoutProp(prop)) layoutChanged = true;
+        ticking++;
         continue;
       }
       const t = a.duration > 0 ? Math.min(1, (now - a.start) / a.duration) : 1;
       a.value = t >= 1 ? a.to : (interpolate(a.from, a.to, ease(t)) ?? a.to);
       if (t >= 1) this._anim.delete(prop);
+      else ticking++;
       if (isLayoutProp(prop)) layoutChanged = true;
     }
     this.style = this._anim.size
@@ -2351,7 +2531,7 @@ export class Node {
     // it *per frame*: a transitioned `color` is a new ink every frame, for
     // this node and for everything inheriting from it.
     if (inheritedTextChanged(this.style, before)) this._retextSubtree();
-    return this._anim.size > 0;
+    return ticking > 0;
   }
 
   /**
@@ -2398,11 +2578,129 @@ export class Node {
     if (this._wantsAttention && this.root?._attentionNodes) {
       this.root._attentionNodes.add(this);
     }
+    if (this._cq !== null && this.root?._containerQueryNodes) {
+      this.root._containerQueryNodes.add(this);
+      // it can see the containers above it now — the constructor's
+      // resolution had no ancestors to find one in
+      this._sizeQueriesChanged();
+    }
     for (const child of this.children) {
       if (!child.isWindow) child._registerSizeQueries();
     }
   }
 
+  /**
+   * The sizes this node's `@container` blocks resolve against: for each name
+   * the style asks about, the nearest ancestor declaring it, in this node's
+   * **logical** pixels — the unit the threshold beside `width: 400` was
+   * written in, so the two numbers mean the same thing. Yoga's computed
+   * size rather than `abs`: inside a flush, `abs` is still the previous
+   * frame's.
+   *
+   * A container that has not been laid out yet contributes nothing, so its
+   * blocks do not apply — the way a capability block does not before the
+   * window exists: the fallback design is the one that works everywhere.
+   * "Laid out" is `_placed` between frames and every attached node while
+   * the window is settling a pass it just ran (`_cqFresh`); a fresh yoga
+   * node answers NaN. Null when no container is known, which is the
+   * identity `resolveQueries` keeps.
+   */
+  _containerSizes() {
+    const names = this._cq?.names;
+    if (!names) return null;
+    let sizes = null;
+    const s = this.scale || 1;
+    const fresh = Boolean(this.root?._cqFresh);
+    for (const name of names) {
+      const c = this._containerFor(name);
+      if (!c) {
+        // In a window and nothing above declares one: a forgotten
+        // declaration, not a component rendered outside its context — that
+        // is what the *named* form is for, and a missing name applies
+        // nothing quietly. `root` rather than `parent`: React builds a
+        // subtree bottom-up, so a node can have a parent and no window yet,
+        // and the container it will find is further up.
+        if (DEV && name === '' && this.root) this._noContainer();
+        continue;
+      }
+      if (!c.yoga || !(fresh || c._placed)) continue;
+      const width = c.yoga.getComputedWidth() / s;
+      const height = c.yoga.getComputedHeight() / s;
+      if (!Number.isFinite(width) || !Number.isFinite(height)) continue;
+      (sizes ??= {})[name] = { width, height };
+    }
+    return sizes;
+  }
+
+  /** `_containerSizes()`, unless this node is pinned at the sizes it is
+   *  looking at — then the sizes its held answer came from, so a restyle
+   *  arriving from React does not undo what the layout pass decided. */
+  _pinnedContainerSizes() {
+    const live = this._containerSizes();
+    const cq = this._cq;
+    const pin = cq.pin;
+    if (!pin) return live;
+    if (pin.key === containersKey(live)) return pin.containers;
+    cq.pin = null;
+    return live;
+  }
+
+  /**
+   * The nearest ancestor whose style declares `container` — any container
+   * for the unnamed query (`''`), the one carrying `name` otherwise, however
+   * many nearer containers that reaches past. A window ends the walk after
+   * offering itself, and a window asks nothing: a `<popup>` inside a
+   * container is a root of its own and asks its own window with `@width`.
+   *
+   * Walked rather than cached: it is a dozen property reads per dependent
+   * per layout pass, and a cache would have to follow every insert, every
+   * reorder and every `container` value that changes above.
+   */
+  _containerFor(name) {
+    if (this.isWindow) return null;
+    for (let n = this.parent; n; n = n.parent) {
+      const c = n.style?.container;
+      if (name === '' ? c === true || typeof c === 'string' : c === name) {
+        return n;
+      }
+      if (n.isWindow) break;
+    }
+    return null;
+  }
+
+  _noContainer() {
+    this._tokenProblem(
+      [
+        `react-x11: <${this.kind}> has an "@container" block and no ` +
+          'container above it — declare one with `container: true` in an ' +
+          "ancestor's style (or name it and ask for it by name), or ask " +
+          'the window with "@width"',
+      ],
+      true,
+      'The block does not apply and the app carries on',
+    );
+  }
+
+  /** Said once per node, in development: a design that cannot settle looks
+   *  like a layout bug, and the frame it is pinned at is the only clue. */
+  _warnContainerOscillation() {
+    const cq = this._cq;
+    if (cq.warned) return;
+    cq.warned = true;
+    const asked = [...(cq.names ?? [])]
+      .map((n) => (n === '' ? 'its container' : `"${n}"`))
+      .join(', ');
+    console.warn(
+      `react-x11: the "@container" blocks on <${this.kind}> cannot settle: ` +
+        `a block that matches at one size of ${asked} changes that size to ` +
+        'one where it no longer matches, and back. A container query must ' +
+        'not move the size it asks about — give the container a size of its ' +
+        'own, or minWidth: 0 and a flexBasis so its content cannot grow it. ' +
+        'The current answer is held until the container moves for another ' +
+        'reason (docs/styling.md#container-queries).',
+    );
+  }
+
   /** Style names this element claims as its own semantics (see WindowNode).
    * Registered elements declare theirs to `registerElement`, so the common
    * case needs no subclass. */
@@ -2686,12 +2984,14 @@ export class Node {
    * swallow the error instead of raising it late. Those throw at once, like
    * the keyed reorder they resemble.
    */
-  _tokenProblem(problems, mounting) {
+  _tokenProblem(problems, mounting, consequence = undefined) {
     if (!STRICT_TOKENS) {
       // every one of them: two misspellings in a style are two things to
       // fix, and a report that named only the first would send someone back
       // for a second run to find the second
-      for (const message of problems) reportStyleError(this, message);
+      for (const message of problems) {
+        reportStyleError(this, message, consequence);
+      }
       return;
     }
     const error = new Error(problems[0]);
@@ -2699,10 +2999,16 @@ export class Node {
     else throw error;
   }
 
-  /** The owning window resized: re-resolve, since a query block may now
-   * match that did not, or the other way round. */
+  /** The owning window resized, the server's answer moved, or a layout pass
+   * moved a container this node asks about: re-resolve, since a query block
+   * may now match that did not, or the other way round. */
   _sizeQueriesChanged() {
-    if (!(this._queried || this._supportsQueried) || this.destroyed) return;
+    if (
+      !(this._queried || this._supportsQueried || this._cq !== null) ||
+      this.destroyed
+    ) {
+      return;
+    }
     const before = this.style;
     // a query block may name `fontSize`, and `_syncStyle` → `_retarget` is
     // what pushes that into the subtree; only the node-local text props are
@@ -2710,7 +3016,19 @@ export class Node {
     this._syncStyle(this.props);
     if (localTextStyleChanged(this.style, before)) this._textContentChanged();
     if (this.yoga && this.style !== before) {
-      applyLayoutStyle(this.yoga, this.style, before);
+      // A block that moved a layout property changed the tree the content
+      // floors were measured from — the debt a style change from React
+      // leaves too (`invalidate`, reason 'props'). It has to be marked as a
+      // *content* change: the live-resize deferral takes a plain
+      // `_floorsDirty` for the drag itself and lays out against the floors
+      // in hand, which are the old arrangement's, and by the time the
+      // catch-up looks the dirty flags are spent and no leaf's height moved
+      // — so the floor of a card that turned from a row into a column would
+      // stay the row's, and yoga would squeeze the column down to it.
+      if (applyLayoutStyle(this.yoga, this.style, before) && this.root) {
+        this.root._floorsDirty = true;
+        this.root._floorsContentDirty = true;
+      }
     }
   }
 
@@ -3699,11 +4017,58 @@ export class Node {
       this.yoga.getComputedWidth(),
       this.yoga.getComputedHeight(),
     );
+    if (this.props.onLayout) this._reportLayout();
     for (const child of this.children) {
       if (!child.isWindow) child.absolutize(this.abs.x, this.abs.y);
     }
   }
 
+  /**
+   * `onLayout`: the rect a layout pass gave this node, reported when it
+   * changed — React Native's contract, and the seam for a decision that is
+   * not a style (docs/react-features.md): how many columns to build, which
+   * component to render. Where the decision *is* a style, a container
+   * query answers it in the same frame instead (docs/styling.md).
+   *
+   * `x`/`y` are the position **within the parent as laid out** — yoga's
+   * answer, which a scroll does not move — rather than the window
+   * coordinates `abs` holds: a list scrolling under the pointer must not
+   * re-render every row on every notch. Logical pixels, this node's own,
+   * the same division `measure()` makes.
+   *
+   * Deferred, like `onViewport`: this runs inside the layout pass, and a
+   * `setState` from the handler would re-enter it. One report per frame,
+   * because `absolutize` runs once, after the container blocks have
+   * settled — a card whose block changed its height reports the height it
+   * ended the frame at, not the one it had between passes.
+   */
+  _reportLayout() {
+    const s = this.scale;
+    const next = {
+      x: this.yoga.getComputedLeft() / s,
+      y: this.yoga.getComputedTop() / s,
+      width: this.abs.width / s,
+      height: this.abs.height / s,
+    };
+    const last = this._lastLayout;
+    if (
+      last &&
+      last.x === next.x &&
+      last.y === next.y &&
+      last.width === next.width &&
+      last.height === next.height
+    ) {
+      return;
+    }
+    this._lastLayout = next;
+    setImmediate(() => {
+      // the handler as it is *now*: React may have re-rendered in between
+      const notify = this.props.onLayout;
+      if (this.destroyed || !notify) return;
+      callHandler(this, 'onLayout', notify, next);
+    });
+  }
+
   /**
    * absolutize's write to `abs`, funneled through one place so a bounded
    * frame's layout diff sees every node the pass actually moved or resized.
@@ -4955,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);
@@ -5458,8 +5824,14 @@ export class TextNode extends Node {
       weight: base.weight,
       style: base.style,
     });
-    const capHeight = font?.metrics?.(base.size)?.capHeight;
-    if (!capHeight) return null; // no metrics: leave the box alone
+    const measured = font?.metrics?.(base.size)?.capHeight;
+    if (!measured) return null; // no metrics: leave the box alone
+    // Whole pixels: the trimmed box's top is the baseline less this, so a
+    // fractional cap height — 9.15px for a 13px face — puts the baseline
+    // between two rows, and the rasteriser lands the letters a row low on
+    // one backend and half-covers two rows on the other. Rounded, the
+    // baseline sits on a pixel wherever the box does.
+    const capHeight = Math.round(measured);
     const shift = halfLeading(layout);
     const firstBaseline = shift + lines[0].baseline;
     const lastBaseline = shift + lines[lines.length - 1].baseline;
@@ -6045,6 +6417,7 @@ export const Scrollable = (Base) =>
         this.yoga.getComputedWidth(),
         this.yoga.getComputedHeight(),
       );
+      if (this.props.onLayout) this._reportLayout();
       this._absolutizeChildren(this.abs.x, this.abs.y);
     }
 
@@ -8496,8 +8869,7 @@ export class TextInputNode extends Node {
       // colour does that on both a light and a dark palette. `#b3d4fc`
       // under the dark palette's near-white ink is 1.3:1, which is nothing.
       // Tinting the surface instead leaves the ink's own contrast intact.
-      ctx.fillStyle =
-        this.props.selectionColor ?? tint(this.theme.accent, 0.35);
+      ctx.fillStyle = this.props.selectionColor ?? this.theme.selection;
       // One band per direction run, not one rectangle between the two caret
       // positions: a range is contiguous in logical order and a line is laid
       // out in visual order, so a selection that crosses into an Arabic word
@@ -8520,7 +8892,7 @@ export class TextInputNode extends Node {
     this._paintPreedit(ctx, valueX, textY, style);
 
     if (this._focused && this._caretOn && a === b) {
-      ctx.fillStyle = this.props.caretColor ?? style.color;
+      ctx.fillStyle = this.props.caretColor ?? this.theme.caret ?? style.color;
       ctx.fillRect(
         valueX + caretX,
         markY,
@@ -8887,8 +9259,7 @@ export class TextAreaNode extends TextInputNode {
       // colour does that on both a light and a dark palette. `#b3d4fc`
       // under the dark palette's near-white ink is 1.3:1, which is nothing.
       // Tinting the surface instead leaves the ink's own contrast intact.
-      ctx.fillStyle =
-        this.props.selectionColor ?? tint(this.theme.accent, 0.35);
+      ctx.fillStyle = this.props.selectionColor ?? this.theme.selection;
       // The bands `textRangeRects` reports — one per line and one per
       // direction run inside a line, which is what a selection crossing into
       // an Arabic word actually covers. Two caret positions and a rectangle
@@ -8997,6 +9368,12 @@ export class WindowNode extends Scrollable(Node) {
     // nodes with `@supports` blocks, re-resolved when the server's answer
     // changes rather than on every layout
     this._supportsQueryNodes = new Set();
+    // nodes with `@container` blocks, re-resolved after every layout pass
+    // against the containers they ask about — see _resolveContainerQueries.
+    // `_cqFresh` is true while a pass this window just ran is being settled,
+    // when every attached node has a computed size to offer
+    this._containerQueryNodes = new Set();
+    this._cqFresh = false;
     // nodes whose child list changed and whose own size is pinned: their new
     // arrangement is only measurable once layout has run (see
     // Node._childListChanged)
@@ -9493,6 +9870,13 @@ export class WindowNode extends Scrollable(Node) {
 
     let size = measure();
     if (this._resolveSizeQueries(size.width, size.height)) size = measure();
+    // …and the container blocks against the arrangement that produced it,
+    // so the window is created at the size its content will actually take
+    if (this._containerQueryNodes.size !== 0) {
+      this._settleContainerQueries(() => {
+        size = measure();
+      });
+    }
 
     // A cap the content decides is its natural size, never below a floor
     // that was named as a number: `WM_NORMAL_HINTS` with a min above its own
@@ -10093,6 +10477,16 @@ export class WindowNode extends Scrollable(Node) {
   _initDnd() {
     const wnd = this.window;
     const X = this.app?.X;
+    // A backend with drop machinery of its own (the cocoa backend's
+    // NSDraggingDestination, src/cocoa/dnd.js): the same DropSession, driven
+    // through its local entry points by the window's transport instead of
+    // by XDND ClientMessages. No property to write, nothing to intern.
+    if (typeof wnd?.attachDropTransport === 'function') {
+      this._dnd = new DropSession(this);
+      registerTopLevel(this);
+      wnd.attachDropTransport(this._dnd, this);
+      return;
+    }
     if (
       !X ||
       typeof X.InternAtom !== 'function' ||
@@ -10137,11 +10531,43 @@ export class WindowNode extends Scrollable(Node) {
    * their top-level's count, since that is where the messages arrive. */
   _registerDropTarget(node) {
     (this._dropTargets ??= new Set()).add(node);
+    this._dndTopLevel()?.window?.dropTargetsChanged?.();
   }
 
   _forgetDropTarget(node) {
     this._dropTargets?.delete(node);
     this._dndOwner()?.forget(node);
+    this._dndTopLevel()?.window?.dropTargetsChanged?.();
+  }
+
+  /** The top-level whose drop session — and transport — this window's
+   * targets roll up into. */
+  _dndTopLevel() {
+    let node = this;
+    while (node && !node._dnd) node = node.parent?.root;
+    return node ?? null;
+  }
+
+  /** The concrete type names every `dropAccept` under this top-level asks
+   * for — what a backend that registers its accepted types up front (the
+   * cocoa backend) adds to its base set. Groups and predicates name none. */
+  _dndConcreteTypes() {
+    const out = new Set();
+    const walk = (wn) => {
+      for (const node of wn._dropTargets ?? []) {
+        const accept = node.props.dropAccept;
+        for (const entry of Array.isArray(accept) ? accept : []) {
+          if (typeof entry === 'string' && !(entry in TYPE_GROUPS)) {
+            out.add(entry);
+          }
+        }
+      }
+      for (const child of wn.children) {
+        if (child.isWindow && !child.isPopup) walk(child);
+      }
+    };
+    walk(this);
+    return [...out];
   }
 
   _dndTargetCount() {
@@ -11001,6 +11427,105 @@ export class WindowNode extends Scrollable(Node) {
     return true;
   }
 
+  /** One layout pass at the window's size, with the content floors it
+   *  needs: fresh ones when something changed them, the ones in hand during
+   *  a live resize, none when nothing moved them. */
+  _layoutStep(width, height) {
+    if (!this._floorsDirty && this._floorsWidth === width) {
+      this._layoutRoot(width, height);
+    } else if (this._deferContentFloors(width)) {
+      this._scheduleFloorsCatchUp();
+      this._layoutRoot(width, height);
+    } else {
+      this._applyContentFloors(width, height);
+    }
+  }
+
+  /**
+   * Resolve the `@container` blocks against the layout just produced, and
+   * lay out again while an answer moves — a container's size is what a pass
+   * *produces*, so it can only be asked about afterwards, and a block that
+   * changed may carry layout properties. `relayout` is whatever pass the
+   * caller runs: `_layoutStep` in a flush, `measure()` while an auto-sized
+   * window is working out how big to be.
+   *
+   * Bounded. Two passes settle the common case (a block that matches at the
+   * width the content took), and nested containers can honestly need a
+   * third — an outer answer moving an inner container past one of its own
+   * thresholds — so the cap is a small fixed number rather than "once".
+   * What it must not do is chase a design no size satisfies; that is
+   * detected per node inside `_resolveContainerQueries`, and pinned.
+   */
+  _settleContainerQueries(relayout) {
+    if (this._containerQueryNodes.size === 0) return;
+    const held = new Map();
+    this._cqFresh = true;
+    try {
+      for (let pass = 0; pass < CONTAINER_QUERY_PASSES; pass++) {
+        if (!this._resolveContainerQueries(held)) return;
+        relayout();
+      }
+      if (DEV && this._resolveContainerQueries(held, false)) {
+        console.warn(
+          'react-x11: "@container" blocks did not settle in ' +
+            `${CONTAINER_QUERY_PASSES} layout passes; the last one stands. ` +
+            'More than two nested containers, each changing the next, is ' +
+            'the shape that gets here (docs/styling.md#container-queries).',
+        );
+      }
+    } finally {
+      this._cqFresh = false;
+    }
+  }
+
+  /**
+   * One round of the above: every dependent whose blocks answer differently
+   * against the containers as they are now is re-resolved, and the caller
+   * hears whether any was. With `apply` false it only answers.
+   *
+   * `held` is what each node has answered so far this frame. A node that
+   * comes back to an answer it already held is a design that oscillates —
+   * the block moves the size it asks about, which CSS forbids by
+   * construction (size containment) and yoga cannot — so it is **pinned**:
+   * the answer it has stands, and stays until the container's size moves
+   * for some other reason. Without the pin the next frame would find the
+   * other answer, apply it, get the other size, and strobe on every layout.
+   */
+  _resolveContainerQueries(held, apply = true) {
+    let changed = false;
+    for (const node of [...this._containerQueryNodes]) {
+      if (node.destroyed) {
+        this._containerQueryNodes.delete(node);
+        continue;
+      }
+      const cq = node._cq;
+      const containers = node._containerSizes();
+      const key = containersKey(containers);
+      if (cq.pin) {
+        if (cq.pin.key === key) continue;
+        cq.pin = null;
+      }
+      const answers = containerAnswers(node._baseStyle, containers);
+      if (answers === cq.answers) continue;
+      if (!apply) return true;
+      let seen = held.get(node);
+      if (seen?.includes(answers)) {
+        cq.pin = { key, containers: cq.containers };
+        if (DEV) node._warnContainerOscillation();
+        continue;
+      }
+      if (!seen) held.set(node, (seen = [cq.answers]));
+      seen.push(answers);
+      node._sizeQueriesChanged();
+      changed = true;
+    }
+    // a block may carry layout properties, so the floors measured from the
+    // styles it is replacing are not the answer any more — the same debt a
+    // window query leaves (`_resolveSizeQueries`)
+    if (changed) this._floorsDirty = true;
+    return changed;
+  }
+
   /**
    * A node in this window has a loop declared on it. Registration is what
    * makes the window watch its own visibility — and only then: a
@@ -11033,6 +11558,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() {
@@ -11206,8 +11738,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
@@ -11313,6 +11856,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
@@ -11375,13 +11923,12 @@ export class WindowNode extends Scrollable(Node) {
       // ledger's rect moves with the shift (issue #398).
       this._laidOut = true;
       this._resolveSizeQueries(width, height);
-      if (!this._floorsDirty && this._floorsWidth === width) {
-        this._layoutRoot(width, height);
-      } else if (this._deferContentFloors(width)) {
-        this._scheduleFloorsCatchUp();
-        this._layoutRoot(width, height);
-      } else {
-        this._applyContentFloors(width, height);
+      this._layoutStep(width, height);
+      // `@container` blocks are answered by the pass, not before it, and a
+      // changed answer is one more pass — before `absolutize`, so the layout
+      // diff below sees one arrangement against the last frame's
+      if (this._containerQueryNodes.size !== 0) {
+        this._settleContainerQueries(() => this._layoutStep(width, height));
       }
       this.abs = { x: 0, y: 0, width, height };
       this._placed = true;
@@ -11441,6 +11988,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:
@@ -11986,6 +12540,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;
@@ -12188,6 +12747,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);