react-x11 2.44.1 → 2.45.1

package/package.json

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

package/src/cocoa/app.js

@@ -1014,8 +1014,11 @@ export class CocoaApp {
         wnd?._shown?.(msg.seq);
       } else if (msg?.type === 'pane-rect') {
         pane.setPaneSize(msg.width, msg.height, msg.scale, msg.screen);
+        if (typeof msg.live === 'boolean') pane.setLive(msg.live);
         this._flushPaneOutbox();
         this._afterInput();
+      } else if (msg?.type === 'pane-live') {
+        pane.setLive(msg.live === true);
       } else if (msg?.type === 'pane-menu-answer') {
         const answer = this._paneMenus?.get(msg.menu);
         this._paneMenus?.delete(msg.menu);
@@ -1687,6 +1690,9 @@ export class CocoaApp {
     const wnd = this._window(ev);
     if (!wnd || wnd.destroyed) return;
     wnd.liveResizing = ev.phase === 'begin';
+    // and what lives in the window without being it hears: a `<Frame>`'s
+    // pane, which has no window of its own to be resized live
+    wnd.emit('liveresize', { live: wnd.liveResizing });
   }
 
   /**

package/src/cocoa/glarea.js

@@ -11,7 +11,7 @@
 // What GlAreaNode needs from us is the child-"window" contract it already
 // speaks (src/glnodes.js): `createWindow({ parent, … })` answering an
 // object with `getContext('opengl', config)`, `setState(rect)`, `map()`,
-// `destroy()`, `requestAnimationFrame`. On X11 that child is a real X
+// `unmap()`, `destroy()`, `requestAnimationFrame`. On X11 that child is a real X
 // window stacked above the parent's drawing; here it is a sublayer of the
 // window's root layer with a high zPosition — the same "GL sits above the
 // 2D" semantics, by the same mechanism the platform gives us. The layer
@@ -153,6 +153,9 @@ export class CocoaGLArea {
       return layer;
     });
     this.rect = null;
+    // Ours to keep, because every `setState` writes the layer's whole prop
+    // set: a geometry change on a hidden surface must not show it again.
+    this._hidden = false;
     this.setState({
       x: options.x ?? 0,
       y: options.y ?? 0,
@@ -178,7 +181,7 @@ export class CocoaGLArea {
       // mirroring the layer is the flip, applied where the compositor is
       // already transforming instead of in anyone's shader.
       transform: { scaleY: -1 },
-      hidden: false,
+      hidden: this._hidden,
     });
     this._context?._resized(rect.width, rect.height);
   }
@@ -200,9 +203,22 @@ export class CocoaGLArea {
   }
 
   map() {
+    this._hidden = false;
     if (!this.destroyed) this._setLayerProps({ hidden: false });
   }
 
+  /**
+   * The other half of `map()`, which this surface went without: a layer is
+   * composited by the WindowServer rather than painted by the window, so a
+   * subtree going off the screen leaves it on screen over what replaced it.
+   * X11 and Wayland unmap the surface's window for this; here the layer's
+   * own `hidden` carries it.
+   */
+  unmap() {
+    this._hidden = true;
+    if (!this.destroyed) this._setLayerProps({ hidden: true });
+  }
+
   /**
    * Everything this layer is handed goes out with Core Animation's implicit
    * actions off. The layer is ours, not a presenter's, so no frame's

package/src/cocoa/panewindow.js

@@ -50,6 +50,8 @@ export class CocoaPaneWindow {
     // polls it through the pane's ref, so both spellings answer
     this.id = this.windowId;
     this.windowNumber = this.windowId;
+    // the host's word, which the pane has no AppKit to hear (`setLive`)
+    this.liveResizing = false;
     this.scale = app.scale ?? 2;
     // Device pixels, as every window's attributes are (`windowAttributes`
     // multiplies the props through once): the size the pane is born at,
@@ -112,6 +114,20 @@ export class CocoaPaneWindow {
    * a host that does not say. A move alone is a `resize` that `moved`, the
    * event a window's own move is, so what is anchored here follows it.
    */
+  /**
+   * Whether the window the pane is in is being resized live, as the host
+   * says (`pane-rect`, `pane-live`, src/frame/index.js): what a window's
+   * `liveResizing` is in a process of its own, where AppKit brackets the
+   * drag of its edge. Core defers a content floor's measurement while it
+   * is (src/nodes/window/size.js), and catches it up the frame after it
+   * ends; and it is announced as a window announces its own.
+   */
+  setLive(live) {
+    if (this.destroyed || this.liveResizing === live) return;
+    this.liveResizing = live;
+    this.emit('liveresize', { live });
+  }
+
   setPaneSize(width, height, scale, screen) {
     if (this.destroyed) return;
     if (scale) this.scale = scale;

package/src/cocoa/window.js

@@ -278,6 +278,12 @@ export class CocoaWindow {
     let list = this._handlers.get(name);
     if (!list) this._handlers.set(name, (list = []));
     list.push(fn);
+    // and the way to stop listening, for a listener that goes before the
+    // window does (`<Frame>`'s, for `liveresize`)
+    return () => {
+      const at = list.indexOf(fn);
+      if (at >= 0) list.splice(at, 1);
+    };
   }
 
   emit(name, ev) {

package/src/foreignnodes.js

@@ -488,18 +488,21 @@ export class ForeignNode extends Node {
     wnd.setBackgroundPixel(pixel);
   }
 
-  setHidden(hidden) {
-    super.setHidden(hidden);
+  /** The client's window is a window of the display system over this one,
+   *  so it follows the whole subtree's visibility — see
+   *  `GlAreaNode._syncSurfaceVisibility`, which answers the same call. */
+  _syncSurfaceVisibility() {
     this._syncMapped();
   }
 
-  /** The container follows `hidden`; the client follows the container,
-   * because an inferior of an unmapped window is not viewable however
-   * mapped it is itself. */
+  /** The container follows whether this subtree is on screen — this node's
+   * own `hidden` flag, or anything above it that took the subtree away; the
+   * client follows the container, because an inferior of an unmapped window
+   * is not viewable however mapped it is itself. */
   _syncMapped() {
     const wnd = this.socket?.window;
     if (!wnd) return;
-    if (this.hidden) wnd.unmap?.();
+    if (this._hiddenInTree()) wnd.unmap?.();
     else wnd.map?.();
   }
 

package/src/frame/index.js

@@ -574,6 +574,20 @@ function PaneHostView({
     let acks = false;
     let inFlight = false;
     let waiting = null;
+    // And whether the window is being resized live — AppKit's drag of its
+    // edge, from its begin to its end (`liveResizing`) — which the pane
+    // has no window to hear. Core defers measuring a content floor for a
+    // drag's length and catches it up after it (src/nodes/window/size.js),
+    // and an element puts off what it would rather do once the drag ends:
+    // a pane measured its floors at every step, a document a pixel wide
+    // among them, and laid a document out whole at every rest of the drag.
+    // With every rect, and on its own where only that changed — the end
+    // of a drag comes after its last size.
+    const hostWindow = node.root?.window;
+    const liveNow = () => hostWindow?.liveResizing === true;
+    const offLive = hostWindow?.on?.('liveresize', (ev) =>
+      s.trySend?.({ type: 'pane-live', live: ev?.live === true }),
+    );
     const transmit = (rect) => {
       sent = rect;
       s.trySend?.({
@@ -581,6 +595,7 @@ function PaneHostView({
         width: rect.width,
         height: rect.height,
         scale: rect.scale,
+        live: liveNow(),
         ...(rect.screen && { screen: rect.screen }),
       });
       if (!acks) return;
@@ -685,6 +700,7 @@ function PaneHostView({
       waiting = null;
       offAnchor?.();
       offFocus?.();
+      if (typeof offLive === 'function') offLive();
       node.defaultCursor = undefined;
       node.root?.events?.refreshCursor();
       node.absolutize = origAbsolutize;

package/src/glnodes.js

@@ -324,6 +324,9 @@ export class GlAreaNode extends Node {
     // same zPosition. The window's hit test reads the list in that order
     // (`EventManager._surfaceAt`).
     this._joinSurfaces();
+    // A surface created inside a subtree that is already hidden — a tab
+    // mounted behind the one on screen — must not come up over it.
+    this._syncSurfaceVisibility();
     this.gl = wnd.getContext('opengl', config);
     // A buffer freed by the display is a frame that can be drawn again — for
     // a frame that was waiting for one. The Cocoa surface and the CGL
@@ -725,8 +728,15 @@ export class GlAreaNode extends Node {
     this.requestFrame();
   }
 
-  setHidden(hidden) {
-    super.setHidden(hidden);
+  /**
+   * The surface is a window of the display system, so it goes when the
+   * subtree does — `display: 'none'` anywhere above it, or React's own
+   * `hidden` for `<Activity>`/`<Suspense>`, on this node or on an ancestor.
+   * `Node._syncSurfaces` calls this for every route; the panes the children
+   * are drawn on follow the same answer.
+   */
+  _syncSurfaceVisibility() {
+    const hidden = this._hiddenInTree();
     if (hidden) this.window?.unmap?.();
     else this.window?.map?.();
     this._overlay?.setHidden(hidden);

package/src/node.d.ts

@@ -750,6 +750,20 @@ export declare class Node {
    * each scroll the pane blits, after layout.
    */
   viewportFixedRects(): Rect[] | null;
+  /**
+   * What this element draws under the viewport of the scroll pane it is in
+   * moved by (dx, dy) device pixels, and what the viewport shows is to stay
+   * where it is on screen: the pane's offsets move by as much, in the
+   * layout pass running now, after it measures what it holds and before it
+   * places it (CSS Scroll Anchoring 1) — a document laid out again at
+   * another width, whose text above the fold broke into more lines or
+   * fewer. Asked of the nearest scroll pane; shifts in one pass add up.
+   * Ask from the layout pass (`measureContent`); asked outside one, the
+   * shift waits for the next and asks for it. A `scrollTo` made since the
+   * last pass drops it, a `scrollIntoView` lands after it, and the result
+   * is clamped as any scroll. Returns whether a pane took it.
+   */
+  anchorScrollBy(dx: number, dy: number): boolean;
   /**
    * How far this element's own drawing reaches past its box, in device
    * pixels on every side — 0, the default, for an element that stays inside

package/src/nodes/invalidate.js

@@ -137,6 +137,36 @@ export class NodeInvalidate {
     return null;
   }
 
+  /**
+   * What this element draws under the viewport of the scroll pane it is
+   * in moved by (dx, dy) device pixels, and what the viewport shows is to
+   * stay where it is on screen: the pane's offsets move by as much, in the
+   * layout pass running now, after it measures what it holds and before it
+   * places it (CSS Scroll Anchoring 1). A document laid out again at
+   * another width is the case: its text above the fold breaks into more
+   * lines or fewer, and the paragraph at the top of the viewport moves
+   * down or up the document by the difference — which, unanswered, scrolls
+   * the reader a page away from where they were.
+   *
+   * Asked of the nearest scroll pane, the one whose viewport the element
+   * is seen through; shifts asked of it in one pass add up. Ask from the
+   * layout pass — `measureContent`, or what it calls — where the pane
+   * places its content after; asked outside one, the shift waits for the
+   * next pass, and asks for it. A `scrollTo` the application made since
+   * the last pass drops it, since the shift was measured against the
+   * offsets before that scroll; a `scrollIntoView` lands after it; and the
+   * pane clamps the result to what it holds, as any scroll. Returns
+   * whether a pane took it: false where nothing scrolls the element.
+   */
+  anchorScrollBy(dx, dy) {
+    for (let n = this.parent; n; n = n.parent) {
+      if (typeof n._anchorScrollBy === 'function' && n.isScroller()) {
+        return n._anchorScrollBy(dx, dy);
+      }
+    }
+    return false;
+  }
+
   /**
    * How far this element's own drawing reaches past its box — device
    * pixels, on every side — or 0, the default, for one that stays inside

package/src/nodes/node.js

@@ -860,12 +860,31 @@ export class Node {
     // window rather than for this subtree — the set is the handful of nodes
     // that declare an `animation`, and each one answers for itself.
     if (this.root?._loopNodes?.size) this.root._refreshLoops();
+    // Same funnel, same reason, one layer down: a surface — a `<glarea>`'s GL
+    // child, an embedded client's window — is a real window of the display
+    // system stacked above everything this window paints, not pixels in its
+    // 2d context. Hiding a subtree takes away its layout and its paint, and
+    // reaches a surface inside it through neither: it would stay on screen,
+    // over whatever is shown in its place, which is what a tab that keeps its
+    // screens mounted does every time it switches.
+    this._syncSurfaces();
     const events = this._focusManager();
     if (!events) return;
     if (visible) events.subtreeRevealed(this);
     else events.subtreeHidden(this);
   }
 
+  /**
+   * Ask every surface in this subtree — this node included — whether it is
+   * still on screen, and map or unmap it to match. Walked rather than kept
+   * in a registry because the subtree whose visibility just changed is
+   * exactly the scope, and all but two elements answer nothing.
+   */
+  _syncSurfaces() {
+    this._syncSurfaceVisibility?.();
+    for (const child of this.children) child._syncSurfaces?.();
+  }
+
   /**
    * Focus this node, as clicking it would: the owning window's focus moves
    * here, `onBlur` fires on whatever had it, `onFocus` here. Also pulls the

package/src/nodes/scrollable.js

@@ -330,6 +330,10 @@ export const Scrollable = (Base) =>
       // the viewport grew, under it. A browser fires `scroll` for each, so
       // `onScroll` hears of them too, once the pass is over.
       const from = { x: this.scrollX, y: this.scrollY };
+      // What the content asked to keep in place lands before them all
+      // (`anchorScrollBy`): it moved under the viewport in this pass, and
+      // a scroll anyone asks for is from where it shows what it did
+      this._applyAnchorShift();
       // A scrollTo held for this pass lands first, so a node asked into view
       // in the same frame is brought in from where that scroll put the pane:
       // the order the two have on a laid-out pane, where scrollTo applies at
@@ -607,6 +611,10 @@ export const Scrollable = (Base) =>
       }
       this.scrollX = next.x;
       this.scrollY = next.y;
+      // a scroll asked for since the last pass is where the pane goes: a
+      // shift the content asks for in the next was measured against the
+      // offsets before it (`_applyAnchorShift`)
+      this._scrolledSincePass = true;
       if (moved) this.props.onScroll?.(this._scrollEvent());
       // A scroll reflows this viewport's contents and nothing else, and the
       // viewport clips them, so the damage is this node's own rect. It is a
@@ -707,6 +715,47 @@ export const Scrollable = (Base) =>
       return true;
     }
 
+    /**
+     * The pane's half of `Node.anchorScrollBy`: a shift of the offsets the
+     * content asked for, added up until the pass applies it
+     * (`_applyAnchorShift`). The pass measures the content again, since
+     * what moved under the viewport moved by being laid out; one asked
+     * outside a pass asks for one.
+     */
+    _anchorScrollBy(dx, dy) {
+      if (!Number.isFinite(dx) || !Number.isFinite(dy)) return false;
+      if (dx === 0 && dy === 0) return true;
+      const shift = (this._anchorShift ??= { x: 0, y: 0 });
+      shift.x += dx;
+      shift.y += dy;
+      this._scrollMeasureDirty = true;
+      const root = this.root;
+      if (root && !root._inFlush) root.invalidate(true, this, 'scroll');
+      return true;
+    }
+
+    /**
+     * Apply the shift the content asked for (`_anchorScrollBy`), before
+     * anything else the pass moves the offsets by: on each axis it scrolls,
+     * the clamp after takes it into the extent just measured. Its
+     * `onScroll` and its claim of the viewport are the pass's, as for a
+     * held `scrollTo`. A scroll the application asked for since the last
+     * pass drops it: the shift was measured against the offsets before
+     * that scroll, which is where the application wants the pane now.
+     */
+    _applyAnchorShift() {
+      const shift = this._anchorShift;
+      const scrolled = this._scrolledSincePass === true;
+      this._scrolledSincePass = false;
+      if (!shift) return;
+      this._anchorShift = null;
+      if (scrolled) return;
+      // `scrollX` is a distance from the start in either direction, and
+      // content that moved towards the end is followed the same way
+      this.scrollX += this.direction === 'rtl' ? -shift.x : shift.x;
+      this.scrollY += shift.y;
+    }
+
     /**
      * Answer a held request (`_holdScrollTo`) against the extent this pass
      * has just measured: each held axis's base, clamped, then each step

package/src/nodes/window/floors.js

@@ -533,10 +533,12 @@ export function setMeasuringShrink(node, axis, out) {
  * It is still laid out, though, and a leaf's answer could reach something
  * that is read through its size. So it is marked only where it cannot:
  *
- * - every box from the root down to it is as wide as something other than
- *   its content — the root offered no room, a width it names, a column
- *   stretching it — so the width the leaf answers is one yoga replaces, and
- *   nothing above it is sized from it;
+ * - every box from `node` down to it is as wide as something other than
+ *   its content — `node` the width the pass gives it (no room, for the
+ *   window; its column's, for a spine root; its own, for a box that sizes
+ *   itself), and below it a width it names or a column stretching it — so
+ *   the width the leaf answers is one yoga replaces, and nothing above it
+ *   is sized from it;
  * - no box is handed a share of space the leaf's height changed, which is
  *   how a height could become somebody's width — an aspect ratio, a column
  *   that wraps, an image sized to the height it is given. Every column from
@@ -656,15 +658,28 @@ function stretchedAlong(node, axis) {
  * names are numbers — a height, a basis (a height, down a column), a floor or
  * a ceiling; and `'unknown'` for a share of something (a percentage), which
  * a pass with no height on offer resolves as it likes.
+ *
+ * A floor of nothing bounds nothing: a box as tall as its content is at
+ * least that tall already, so its height is its content's. It is how a box
+ * says it may shrink, and a browser's page has one on every box from the
+ * window down to its scroller, so that a page taller than the window
+ * scrolls. Read as a height of the box's own, it stopped the walk at the
+ * first of them, where the scroller gives way: the whole document in the
+ * scroller was set a word to a line each time the tree was measured, 100
+ * to 250 ms of a frame for a long Wikipedia article, and nothing read any
+ * of it. And it took the box pinned to both edges of such a column for one
+ * whose height nothing in flow decides, which it is.
  */
 function heightOf(yoga) {
+  const floor = yoga.getMinHeight();
   let own = false;
   for (const value of [
     yoga.getHeight(),
     yoga.getFlexBasis(),
-    yoga.getMinHeight(),
+    floor.value === 0 ? null : floor,
     yoga.getMaxHeight(),
   ]) {
+    if (value === null) continue;
     if (value.unit === Yoga.UNIT_PERCENT) return 'unknown';
     if (value.unit === Yoga.UNIT_POINT) own = true;
   }

package/src/nodes/window/size.js

@@ -354,12 +354,28 @@ export class WindowSize {
     if (axis === 'width') {
       const shrunk = [];
       setMeasuringShrink(root, axis, shrunk);
+      // Nothing reads a root's own width — only heights travel up a spine
+      // (spine.js) — so what it holds is read only where a floor is written
+      // from it, as down the window's columns, and a leaf that is the root
+      // is laid out at the width its column offers, which is no answer of
+      // its own: a document in a scroller is a root when it changes.
+      const read = NO_UNREAD_WIDTHS || this._readEveryWidth;
+      const unread = [];
+      if (!read && root._measureFn) {
+        root._widthUnread = true;
+        unread.push(root);
+      } else if (!read) {
+        markUnreadLeaves(root, unread);
+      }
       this._scopedFloorPasses += 1;
-      yoga.calculateLayout(widths.widthPass, undefined, dir);
-      const span = contentSpan(root, axis, null, this);
-      root._floorW = declaresOwnMinimum(root, axis)
-        ? yoga.getComputedWidth()
-        : span;
+      try {
+        yoga.calculateLayout(widths.widthPass, undefined, dir);
+      } finally {
+        for (const leaf of unread) leaf._widthUnread = false;
+      }
+      const span = contentSpan(root, axis, null, this, read);
+      const own = declaresOwnMinimum(root, axis);
+      if (own || read) root._floorW = own ? yoga.getComputedWidth() : span;
       restoreShrink(shrunk);
       return;
     }
@@ -443,9 +459,18 @@ export class WindowSize {
     if (axis === 'width') {
       const shrunk = [];
       setMeasuringShrink(boundary, axis, shrunk);
+      // its own extent is its style's, so what it holds is read only where
+      // a floor is written from it, as down the window's columns
+      const read = NO_UNREAD_WIDTHS || this._readEveryWidth;
+      const unread = [];
+      if (!read) markUnreadLeaves(boundary, unread);
       this._scopedFloorPasses += 1;
-      yoga.calculateLayout(undefined, undefined, dir);
-      contentSpan(boundary, axis, null, this);
+      try {
+        yoga.calculateLayout(undefined, undefined, dir);
+      } finally {
+        for (const leaf of unread) leaf._widthUnread = false;
+      }
+      contentSpan(boundary, axis, null, this, read);
       restoreShrink(shrunk);
       return;
     }

package/src/testing/harness.js

@@ -559,32 +559,50 @@ function restoreFrameClock() {
 }
 
 /**
- * Retry `fn` until it stops throwing, flushing between attempts.
+ * Retry `fn` until it stops throwing, flushing between attempts, and resolve
+ * with what it returned once that is on screen.
  *
  * The tool for anything whose arrival is not a single deterministic step:
  * an async rich-content reflow, an image decode, a timer, or a repaint whose
- * cause travelled through the X connection and back. Each attempt is
- * preceded by an `act()`, so waiting also *advances* — this is not a sleep
- * with a condition on it.
+ * cause travelled through the X connection and back. Each retry is preceded
+ * by an `act()`, so waiting also *advances* — this is not a sleep with a
+ * condition on it.
  *
  * ```js
  * await waitFor(async () => {
  *   assert.notDeepStrictEqual(await pixelAt(ctx, x, y), before);
  * });
+ * const row = await waitFor(() => screen.getByText('notes.txt'));
+ * await userEvent.click(row);
  * ```
+ *
+ * **The attempt that passes is followed by an `act()` too.** What it found
+ * can have arrived in the sleep before it — an fs read, a timer — and that
+ * commits outside act, on React's own scheduler, while the frame that lays
+ * it out runs on the window's clock, which need not have ticked since.
+ * Without it, a node it returned could have no rect yet, and the click after
+ * it would throw `has no laid-out rect yet` (#904). It follows whichever
+ * attempt passed, the first included, since the commit can land before
+ * `waitFor` is called. And it has to come after the attempt: an `act()`
+ * before each one leaves the same gap in its own closing round trip, after
+ * the frame it ran.
  */
 export async function waitFor(fn, { timeout = 2000, interval = 10 } = {}) {
   const deadline = Date.now() + timeout;
   let last;
   for (;;) {
+    let found;
     try {
-      return await fn();
+      found = await fn();
     } catch (err) {
       last = err;
+      if (Date.now() >= deadline) throw last;
+      await act();
+      await new Promise((resolve) => setTimeout(resolve, interval));
+      continue;
     }
-    if (Date.now() >= deadline) throw last;
     await act();
-    await new Promise((resolve) => setTimeout(resolve, interval));
+    return found;
   }
 }
 

package/src/testing/index.d.ts

@@ -174,6 +174,13 @@ export interface A11ySpy {
   uninstall(): void;
 }
 
+/**
+ * Testing Library's four families over the retained node tree: `getBy*`
+ * (exactly one, or throw), `queryBy*` (one or null), `getAllBy*` (one or
+ * more), and `findBy*` — `getBy*` under {@link waitFor}, with its options and
+ * defaults, so it retries until the node appears and resolves once a frame
+ * has laid it out.
+ */
 export interface Queries {
   getByText(text: string | RegExp, options?: TextMatchOptions): DrawnNode;
   getAllByText(text: string | RegExp, options?: TextMatchOptions): DrawnNode[];
@@ -339,7 +346,16 @@ export function setAppearance(values: PinnedAppearance): Promise<void>;
 /** Drain in-flight requests on a connection. */
 export function settle(app: NtkApp, roundTrips?: number): Promise<void>;
 
-/** Retry until it stops throwing, `act`-ing between attempts. */
+/**
+ * Retry until it stops throwing, `act`-ing between attempts — and once more
+ * after the attempt that passed, so what it resolves with is on screen: a
+ * node it found has been laid out, and a click on it lands.
+ *
+ * ```ts
+ * const row = await waitFor(() => screen.getByText('notes.txt'));
+ * await userEvent.click(row);
+ * ```
+ */
 export function waitFor<T>(
   fn: () => T | Promise<T>,
   options?: WaitOptions,

package/src/testing/queries.js

@@ -12,13 +12,13 @@
 //   getBy*    exactly one, or throw
 //   queryBy*  one or null, never throws — the way to assert absence
 //   getAllBy* one or more, or throw
-//   findBy*   getBy*, retried until it appears or the timeout expires
+//   findBy*   getBy* under waitFor: retried until it appears or the timeout
+//             expires, and laid out by the time it resolves
 
 import { queryAllByComponent, componentInventory } from './components.js';
+import { waitFor } from './harness.js';
 import { roleNameOf } from '../a11y.js';
 
-const DEFAULT_TIMEOUT = 1000;
-
 /** Depth-first, in paint order, including `<popup>` subtrees. */
 function walk(node, visit) {
   if (!node || node.destroyed) return;
@@ -97,20 +97,6 @@ function one(root, found, what, printTree = inventory) {
   );
 }
 
-async function retry(fn, { timeout = DEFAULT_TIMEOUT, interval = 20 } = {}) {
-  const deadline = Date.now() + timeout;
-  let last;
-  for (;;) {
-    try {
-      return fn();
-    } catch (err) {
-      last = err;
-      if (Date.now() >= deadline) throw last;
-      await new Promise((r) => setTimeout(r, interval));
-    }
-  }
-}
-
 /**
  * The queries, bound to a subtree. `within(node)` is this with a different
  * root; `screen` is this bound to whatever `renderX11` mounted last.
@@ -199,9 +185,12 @@ export function within(root) {
       if (found.length > 1) return one(root, found, label(args[0]));
       return found[0] ?? null;
     };
+    // Through waitFor rather than a loop of its own: what this resolves with
+    // has to be laid out, or a click on it throws, and waitFor is what runs
+    // the frame before resolving
     q[`find${suffix}`] = (...args) => {
       const options = args.length > 1 ? args[args.length - 1] : undefined;
-      return retry(() => q[`get${suffix}`](...args), options);
+      return waitFor(() => q[`get${suffix}`](...args), options);
     };
   }
   return q;