react-x11 2.45.0 → 2.45.2

package/package.json

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

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/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/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/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/testing/events.js

@@ -15,6 +15,7 @@
 // async and `fireEvent` is not.
 
 import { act } from './harness.js';
+import { describeNode } from './queries.js';
 import { keysymOf, MOD, XK_RETURN } from '../keysyms.js';
 
 /** The window node that owns a drawn node (a node, or a window itself). */
@@ -22,15 +23,23 @@ function rootWindow(node) {
   return node?.isWindow ? node : (node?.root ?? null);
 }
 
+const NOT_IN_A_WINDOW =
+  'react-x11/test: the target is not inside a realized window — did you ' +
+  'await renderX11(), or has it unmounted?';
+
 /** A node's centre in **screen** coordinates, which is what injection takes. */
 export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   const win = rootWindow(node);
-  if (!win?.window) {
-    throw new Error(
-      'react-x11/test: the target is not inside a realized window — did you ' +
-        'await renderX11(), or has it unmounted?',
-    );
+  // Asked before the rect, which neither kind of node gives up: one that
+  // has unmounted, or that something hides, keeps the rect it was last laid
+  // out at, and what is at that spot now is whatever was behind it. The hit
+  // test passes over a hidden node, and an unmounted one is in no tree, so
+  // a pointer aimed there could only reach something else, and nothing
+  // would say so.
+  if (node?.destroyed || hiddenBy(node)) {
+    throw new Error(noRectMessage(node, win));
   }
+  if (!win?.window) throw new Error(NOT_IN_A_WINDOW);
   const origin = win.window._screenOrigin ?? {
     x: win.window.x ?? 0,
     y: win.window.y ?? 0,
@@ -44,10 +53,7 @@ export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   }
   const abs = node.abs;
   if (!abs || (abs.width === 0 && abs.height === 0)) {
-    throw new Error(
-      `react-x11/test: <${node.kind}> has no laid-out rect yet. Layout runs ` +
-        'on the frame clock, so `await act()` before pointing at it.',
-    );
+    throw new Error(noRectMessage(node, win));
   }
   return {
     x: Math.round(origin.x + abs.x + abs.width / 2 + dx),
@@ -56,8 +62,101 @@ export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   };
 }
 
+/**
+ * Why a node has no rect to aim at, worded as what to do about it. Only one
+ * answer is a matter of waiting, and its advice, `await act()`, is wrong for
+ * every other: no frame gives a size to a node that layout has already
+ * placed at 0×0. Asked in this order:
+ *
+ * - it has unmounted;
+ * - it is hidden: by its own `display: 'none'` or an ancestor's, by React,
+ *   or in a window kept unmapped by `hidden` or by React. That comes before
+ *   asking whether layout reached it, because a `<box>` with
+ *   `display: 'none'` never places its children at all.
+ *
+ *   These first two are asked whatever the node's rect: `screenPointOf`
+ *   comes here for them before it looks, since the rect such a node keeps
+ *   is where it was, not where anything is;
+ * - it has no box of its own: a span, an SVG shape;
+ * - layout has not placed it yet (`_placed`), or the window owes a pass
+ *   (`needsLayout`) that may still give it a size. A pending frame is no
+ *   witness: a paced window holds one with nothing scheduled;
+ * - layout placed it, at 0×0.
+ */
+function noRectMessage(node, win) {
+  const name = describeNode(node);
+  if (node.destroyed) {
+    return (
+      `react-x11/test: ${name} has unmounted, so it is nowhere on screen to ` +
+      'point at. If something replaced it, query for that instead.'
+    );
+  }
+  const hider = hiddenBy(node);
+  if (hider) {
+    const self = hider === node;
+    const has = self ? 'has' : 'which has';
+    const how =
+      hider.isWindow && hider.props.hidden
+        ? `${has} \`hidden\``
+        : hider.style?.display === 'none'
+          ? `${has} \`display: 'none'\``
+          : `${self ? 'is hidden by React' : 'which React has hidden'}, in ` +
+            'an `<Activity mode="hidden">` or a `<Suspense>` showing its ' +
+            'fallback';
+    return (
+      `react-x11/test: ${name} ` +
+      (self ? how : `is inside ${describeNode(hider)}, ${how}`) +
+      ', so there is nothing on screen to point at, and `await act()` will ' +
+      'not change that. ' +
+      (self
+        ? 'Show it before pointing at it.'
+        : 'Show that before pointing at anything inside it.')
+    );
+  }
+  if (!node.yoga) {
+    let owner = node.parent;
+    while (owner && !owner.yoga) owner = owner.parent;
+    return (
+      `react-x11/test: ${name} has no box of its own: it is laid out as part ` +
+      `of ${owner ? describeNode(owner) : 'its parent'}, so there is no ` +
+      'rect to point at. Point at that instead, with `{ dx, dy }` to reach ' +
+      'a spot inside it.'
+    );
+  }
+  if (!node._placed || win.needsLayout) {
+    return (
+      `react-x11/test: <${node.kind}> has no laid-out rect yet. Layout runs ` +
+      'on the frame clock, so `await act()` before pointing at it.'
+    );
+  }
+  return (
+    `react-x11/test: ${name} was laid out at 0×0, so there is nothing on ` +
+    'screen to point at. Layout has run since it last changed, so ' +
+    '`await act()` will not give it a size: give it one, with `width` and ' +
+    '`height`, `flexGrow` or content to size it, or point at an ancestor ' +
+    'or a child that has one. If its size comes from content still on its ' +
+    'way, such as an image that is loading, wait for that with `waitFor`.'
+  );
+}
+
+/** The node that takes `node` off the screen — itself or the nearest
+ * ancestor with `display: 'none'` or hidden by React, up to and including
+ * its window, which a `hidden` prop or React keeps unmapped — or null when
+ * nothing does. The same walk as the renderer's `_hiddenInTree`. */
+function hiddenBy(node) {
+  for (let n = node; n; n = n.parent) {
+    if (n.hidden || n.style?.display === 'none') return n;
+    if (n.isWindow) break;
+  }
+  return null;
+}
+
 function serverOf(node) {
-  const server = rootWindow(node)?.app?._reactX11TestServer;
+  // what a target that is no node at all — a `queryBy*` that found nothing —
+  // is told by `screenPointOf`, for the calls that never ask it
+  const win = rootWindow(node);
+  if (!win) throw new Error(NOT_IN_A_WINDOW);
+  const server = win.app?._reactX11TestServer;
   if (!server) {
     throw new Error(
       'react-x11/test: fireEvent needs the in-process X server, so it needs a ' +
@@ -142,10 +241,13 @@ export const fireEvent = {
     fireEvent.mouseMove(node, options);
   },
 
-  /** Move the pointer off the node, which is what produces a leave. */
-  mouseLeave(node, options = {}) {
-    const { server } = screenPointOf(node, options);
-    server.injectPointerMove(0, 0);
+  /**
+   * Move the pointer off the node, to the screen's origin, which is what
+   * produces a leave. Nothing is aimed at, so the node may since have been
+   * hidden or unmounted: it only names the connection.
+   */
+  mouseLeave(node) {
+    serverOf(node).injectPointerMove(0, 0);
   },
 
   mouseDown(node, options = {}) {
@@ -157,9 +259,13 @@ export const fireEvent = {
     for (const kc of modifiers.reverse()) server.injectKey(kc, false);
   },
 
+  /**
+   * Release the button wherever the pointer is — a `mouseMove` first puts
+   * it somewhere else. The node only names the connection, so it may be one
+   * the press hid or unmounted: the gesture can still end.
+   */
   mouseUp(node, options = {}) {
-    const { server } = screenPointOf(node, options);
-    server.injectButton(options.button ?? 1, false);
+    serverOf(node).injectButton(options.button ?? 1, false);
   },
 
   /** Press and release — the renderer synthesises the click from the pair. */

package/src/testing/harness.js

@@ -56,23 +56,84 @@ const DEFAULT_SCREEN = { width: 1280, height: 800 };
  * cheapest request with a reply, and its reply cannot arrive before every
  * request queued ahead of it has been processed — which is what makes it a
  * barrier rather than a sleep.
+ *
+ * **On a connection that is going, it resolves at once.** Nothing there will
+ * be answered, and a test that ends its connection still has `act()`,
+ * `waitFor` and `cleanup()` to get through — the last from an `afterEach`.
+ * node-x11 reports the two ways a connection goes very differently:
+ *
+ * - **The app closed it.** From the moment `close()` begins, every request
+ *   throws `client is in closing state` — synchronously, which inside the
+ *   promise below is a rejection.
+ * - **The server ended it** — it exited, or killed the client. All node-x11
+ *   says is an `end` event: it goes on taking requests and never answers
+ *   them, or anything that was in flight, so the round trip waits forever.
+ *   That is the route a test of `onDisconnect` has to take: over the
+ *   in-process stream pair, a client that closed its own connection never
+ *   hears it end.
  */
 export function settle(app, roundTrips = 2) {
   const X = app?.X;
   if (typeof X?.GetInputFocus !== 'function') return Promise.resolve();
+  // renderX11 settles as it mounts, so its connection is watched before a
+  // test can end it
+  const watch = watchEnd(X);
   let chain = Promise.resolve();
   for (let i = 0; i < roundTrips; i++) {
     chain = chain.then(
       () =>
         new Promise((resolve) => {
-          // resolve either way: a closing connection must not hang a test
-          X.GetInputFocus(() => resolve());
+          if (connectionGone(X)) return resolve();
+          const done = () => {
+            watch.waiting.delete(done);
+            resolve();
+          };
+          watch.waiting.add(done);
+          try {
+            X.GetInputFocus(done);
+          } catch {
+            // refused by a rule the check above does not know: whatever the
+            // reason, a request that never went out has nothing to drain
+            done();
+          }
         }),
     );
   }
   return chain;
 }
 
+// Each connection settle() has met: whether the server has ended it, and the
+// round trips waiting on it, which the end has to answer since no reply will.
+const watched = new WeakMap();
+
+function watchEnd(X) {
+  let watch = watched.get(X);
+  if (!watch) {
+    watch = { ended: false, waiting: new Set() };
+    watched.set(X, watch);
+    X.once?.('end', () => {
+      watch.ended = true;
+      for (const done of watch.waiting) done();
+    });
+  }
+  return watch;
+}
+
+/**
+ * Whether a request on this connection would go unanswered: the app began
+ * closing it, or its stream has ended — the test ntk makes before releasing
+ * anything (`connectionGone`, ntk's lib/cleanup.js) — or the server ended
+ * it, which only the `end` event says.
+ */
+function connectionGone(X) {
+  return Boolean(
+    X?._closing ||
+    X?.stream?.destroyed ||
+    X?.stream?.writableEnded ||
+    watched.get(X)?.ended,
+  );
+}
+
 async function createXServerApp({ screen, fonts }) {
   const [{ default: xserver }, ntk] = await Promise.all([
     optional('x11/lib/xserver/index.js', 'is the in-process X server'),
@@ -340,7 +401,15 @@ export async function act(fn, only = null) {
   for (const entry of entries) await settle(entry.app);
 }
 
-/** Run the frame the scheduler would have run, for every window in a root. */
+/**
+ * Run the frame the scheduler would have run, for every window in a root.
+ *
+ * Not skipped on a connection that has gone. The harm a frame can do there
+ * is to throw, which it would only once the app is closing, and the frame
+ * declines on such a connection before it sends a thing (`_flushFrame`); on
+ * one the server ended, its requests are taken and go nowhere. A check here
+ * would be a second copy of the frame's own.
+ */
 function flushFrames(entry) {
   for (const node of windowNodesOf(entry.windowNode)) {
     if (!node.window) continue;
@@ -359,12 +428,17 @@ async function unmountEntry(entry) {
   // before the unmount, so the teardown's own hook traffic is not recorded
   entry.at?.uninstall();
   try {
-    entry.root.unmount?.();
+    // awaited, or the catch is never reached: unmount is async
+    await entry.root.unmount?.();
   } catch {
     // a root whose connection already died: nothing left to unmount
   }
   await settle(entry.app);
-  if (entry.ownsApp) {
+  // A connection that is already going is not closed again. close() begins
+  // with a round trip, which one the test closed refuses by throwing, and
+  // which one whose stream has ended — the server's doing, or a dispose —
+  // never answers, hanging the teardown
+  if (entry.ownsApp && !connectionGone(entry.app.X)) {
     try {
       await entry.app.close?.();
     } catch {
@@ -559,32 +633,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[];
@@ -336,10 +343,23 @@ export function cleanup(): Promise<void>;
  */
 export function setAppearance(values: PinnedAppearance): Promise<void>;
 
-/** Drain in-flight requests on a connection. */
+/**
+ * Drain in-flight requests on a connection. On one that has gone — closed by
+ * the app, or ended by the server — it resolves at once, since nothing there
+ * will be answered.
+ */
 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,
@@ -445,8 +465,14 @@ export interface KeyOptions {
 export const fireEvent: {
   mouseMove(node: DrawnNode, options?: PointerOptions): void;
   mouseEnter(node: DrawnNode, options?: PointerOptions): void;
+  /** Move the pointer to the screen's origin, which is a leave. Aims at
+   *  nothing: `node` only names the connection, and may since have been
+   *  hidden or unmounted. */
   mouseLeave(node: DrawnNode, options?: PointerOptions): void;
   mouseDown(node: DrawnNode, options?: PointerOptions): void;
+  /** Release `button` wherever the pointer is — move it first to release
+   *  somewhere else. Aims at nothing: `node` only names the connection, and
+   *  may be one the press hid or unmounted. */
   mouseUp(node: DrawnNode, options?: PointerOptions): void;
   click(node: DrawnNode, options?: PointerOptions): void;
   doubleClick(node: DrawnNode, options?: PointerOptions): void;
@@ -475,6 +501,7 @@ export const userEvent: {
   click(node: DrawnNode, options?: PointerOptions): Promise<void>;
   doubleClick(node: DrawnNode, options?: PointerOptions): Promise<void>;
   hover(node: DrawnNode, options?: PointerOptions): Promise<void>;
+  /** `fireEvent.mouseLeave`, flushed: aims at nothing. */
   unhover(node: DrawnNode, options?: PointerOptions): Promise<void>;
   /** A scroll in notches; `smooth` takes fractions of one, as a touchpad
    *  measures them. */
@@ -501,7 +528,12 @@ export const userEvent: {
   }): Promise<void>;
 };
 
-/** A node's centre in screen coordinates. */
+/**
+ * A node's centre in screen coordinates. Throws, saying why, for a node
+ * with no rect: not laid out yet, laid out at 0×0, or laid out as part of
+ * another node — and for one that is hidden or has unmounted, whatever rect
+ * it kept, which is where it was and not where anything is.
+ */
 export function screenPointOf(
   node: DrawnNode,
   options?: { dx?: number; dy?: number },

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;
@@ -66,11 +66,24 @@ export function roleOf(node) {
   return roleNameOf(node) ?? node.kind;
 }
 
-function describe(node) {
-  const text = textOf(node).trim();
+/** A node the way an error names it: its kind, its `data-testname` and the
+ * start of its text — what a test author can find it by. A `<popup>` is a
+ * window to the renderer, and is named as the element it was written as.
+ * The text is read whether or not the node is still mounted, unlike
+ * `textOf`'s: one that has unmounted presents nothing now, and is named by
+ * what it said. A mounted node holds no unmounted child, so for one of those
+ * the two read the same. */
+export function describeNode(node) {
+  let text = '';
+  (function read(n) {
+    if (typeof n.text === 'string') text += n.text;
+    for (const child of n.children ?? []) read(child);
+  })(node);
+  text = text.trim();
   const name = node.props?.['data-testname'];
+  const tag = node.isPopup ? 'popup' : node.kind;
   return (
-    `<${node.kind}${name ? ` data-testname="${name}"` : ''}>` +
+    `<${tag}${name ? ` data-testname="${name}"` : ''}>` +
     (text ? ` ${JSON.stringify(text.slice(0, 40))}` : '')
   );
 }
@@ -79,7 +92,7 @@ function inventory(root, limit = 12) {
   const lines = [];
   walk(root, (n) => {
     if (n.kind === 'textchunk' || n.kind === 'textspan') return;
-    if (lines.length < limit) lines.push(`  ${describe(n)}`);
+    if (lines.length < limit) lines.push(`  ${describeNode(n)}`);
   });
   return lines.join('\n');
 }
@@ -93,24 +106,10 @@ function one(root, found, what, printTree = inventory) {
   }
   throw new Error(
     `react-x11/test: found ${found.length} elements for ${what}, expected one:\n` +
-      found.map((n) => `  ${describe(n)}`).join('\n'),
+      found.map((n) => `  ${describeNode(n)}`).join('\n'),
   );
 }
 
-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 +198,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;