react-x11 2.54.0 → 2.55.1

package/docs/components.md

@@ -512,6 +512,7 @@ import { Select } from 'react-x11';
 | `labelStyle`            | the caption's style, over `text`          |
 | `chevronStyle`          | the chevron's style, over `textMuted`     |
 | `native`, `nativeMenu`  | the platform's bezel, and its menu        |
+| `open`, `onOpenChange`  | whether the menu is down                  |
 
 `style` restyles the trigger and the two slots what is inside it, keeping the
 menu, keyboard, type-ahead and focus ring. A borderless select in a line of
@@ -549,6 +550,23 @@ keeps the drawn menu. Elsewhere, or on an older bridge, the menu is drawn. A
 platform menu dismisses itself (Escape, a click outside, the app losing
 focus), and the select hears a pick or nothing.
 
+**Whether the menu is down** is told through `onOpenChange(open)`, each time
+it drops or goes, the drawn menu or the platform's, whatever moved it. With
+`open` the owner holds it, as `value` holds the option: the menu drops when
+`open` goes `true` and goes when it goes `false`, and a press, a key, a pick
+or a click outside asks `onOpenChange` instead. A menu that cannot drop, or
+that goes by itself — the platform's dismissing itself, the trigger
+scrolling out of view — is told as `false`, so an owner that keeps what it
+is told keeps what is on screen; a change the owner made is not told back.
+That is a browser's `select.showPicker()` and `:open`, which `<Html>` in
+`@react-x11/components` answers with it:
+
+```jsx
+const [open, setOpen] = useState(false);
+<Button label="Choose" onPress={() => setOpen(true)} />
+<Select value={v} options={opts} onChange={pick} open={open} onOpenChange={setOpen} />
+```
+
 **Behaviour.** The menu opens on the **press**, as in every desktop toolkit;
 a press while it is up closes it. Space and Enter toggle it; Escape, focus
 loss, losing the window (switching applications) or picking close it. The

package/docs/elements.md

@@ -1360,7 +1360,56 @@ Wayland the field is also declared `sensitive_data` to the input method,
 with no surrounding text offered ([events.md](events.md#input-methods)).
 
 **Ref**: the node, plus `value`, `undo()` / `redo()` and `canUndo` /
-`canRedo` — enough for a toolbar button beside the field.
+`canRedo` — enough for a toolbar button beside the field — and the
+selection, below.
+
+### The selection, from outside
+
+The ref has a DOM input's selection API, with the DOM's names and the DOM's
+units, so a copy-link box, a search field that selects on focus or an input
+mask is written as it would be against a DOM input:
+
+```jsx
+const link = useRef(null);
+<textinput
+  ref={link}
+  defaultValue={url}
+  onFocus={() => link.current.select()}
+/>;
+// an emoji picker: an insert at the caret, and the caret after it
+const field = message.current;
+const { value, selectionStart: a, selectionEnd: b } = field;
+field.value = value.slice(0, a) + emoji + value.slice(b);
+field.setSelectionRange(a + emoji.length, a + emoji.length);
+```
+
+| on the node                                 |                                                                           |
+| ------------------------------------------- | ------------------------------------------------------------------------- |
+| `selectionStart`, `selectionEnd`            | where the selection starts and ends — the caret's offset where nothing is |
+| `selectionDirection`                        | `'forward'`, `'backward'` or `'none'`: which end the caret is at          |
+| `setSelectionRange(start, end, direction?)` | select `[start, end)`; equal offsets put a bare caret                     |
+| `select()`                                  | select the whole value                                                    |
+
+- **Offsets are UTF-16 code units**, as the DOM's are and as a JavaScript
+  string is indexed — `value.slice(selectionStart, selectionEnd)` is what is
+  selected — though `maxLength` and the caret inside the field count code
+  points. One that falls inside a surrogate pair is the character's start.
+- **Clamped as the DOM clamps them**: each end to the value, a start past
+  the end moved back to it. Setting `selectionStart` past the end takes the
+  end with it, and `selectionEnd` before the start takes the start back.
+- **The caret is at the end**, or at the start for `'backward'`, so
+  Shift+arrow goes on from there. A direction set reads back as it was set,
+  `'none'` over a range included, until the user moves an end; after that
+  it is where the caret is, and `'none'` for a bare one.
+- **It is the field's selection**: drawn while the field has the focus — an
+  unfocused field draws none, as a browser's does — and then the one lit
+  range on screen; Backspace deletes it, typing replaces it, and the next
+  edit is a new undo step. What the user selects is what the getters read.
+- **It does not take PRIMARY.** On X11 PRIMARY is what the user last
+  selected, for a middle click elsewhere; a field a script selects on focus
+  would otherwise replace it every time it was tabbed into.
+
+`<textarea>` has the same, across its lines.
 
 ### Undo
 
@@ -1899,9 +1948,10 @@ frame.
 </glarea>
 ```
 
-- **Cocoa**: one transparent layer over the whole surface, composited by
+- **Cocoa**: one transparent layer per child, as big as the child,
+  stacked above the surface in the children's order and composited by
   Core Animation — a translucent fill, antialiased edge or shadow blends
-  with the GL frame.
+  with the GL frame and with the children under it.
 - **X11**: one child window per child, stacked above the surface in the
   children's order and cut (SHAPE) to where the child painted half its
   alpha or more; the GL frame shows everywhere else. A translucent pixel
@@ -1910,10 +1960,11 @@ frame.
   (`react-x11/test`'s server) a pane is the child's whole rectangle,
   `clearColor` where unpainted.
 
-A child that only moves (its `left` or `top`) has its pixels copied, not
-repainted — only uncovered strips are drawn, and panes it passes over are
-untouched — so content panned over a scene is cheap; scroll panes among the
-children scroll the same way.
+A child that only moves (its `left` or `top`) is not repainted — on Cocoa
+its layer moves, and on X11 its pixels are copied and only uncovered strips
+are drawn; panes it passes over are untouched either way — so content
+panned over a scene is cheap; scroll panes among the children scroll the
+same way.
 [`REACT_X11_NO_SCROLL_BLIT=1`](debugging.md#react_x11_no_scroll_blit1)
 turns the copies off.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.54.0",
+  "version": "2.55.1",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "bin": {

package/src/cocoa/app.js

@@ -508,6 +508,17 @@ export class CocoaApp {
     return new CocoaOverlayPane(this, attributes);
   }
 
+  /**
+   * That a `<glarea>`'s children each take a pane of their own here, as on
+   * X11, rather than one pane over the whole surface: Core Animation stacks
+   * the layers (`CocoaOverlayPane.stackAt`), and each is only as big as its
+   * child, so a minimap's viewport moving pushes the minimap's pixels and
+   * not the surface's (src/gloverlay.js).
+   */
+  get overlaysPerChild() {
+    return true;
+  }
+
   /**
    * The Frame host seam (src/frame/index.js): a pane's composited region
    * in this window. Its presence is what routes <Frame> to the shared-
@@ -1704,11 +1715,32 @@ export class CocoaApp {
    * again once the WindowServer lets go of it too
    * (`CocoaWindow._surfaceReleased`); the tick at the end of this batch
    * runs the frame it was holding.
+   *
+   * A buffer that is no window's is a `<glarea>`'s, which waits on it the
+   * same way (`watchSurfaceRelease`).
    */
   _routeSurfaceReleased(ev) {
     for (const wnd of this._windows.values()) {
       if (wnd._surfaceReleased(ev.id)) return;
     }
+    const watcher = this._surfaceWatchers?.get(ev.id);
+    if (!watcher) return;
+    this._surfaceWatchers.delete(ev.id);
+    watcher();
+  }
+
+  /**
+   * Call `fn` once `surface-released` names IOSurface `id`: a buffer a
+   * worker's flip took off a layer that no window owns. The returned
+   * function stops watching.
+   */
+  watchSurfaceRelease(id, fn) {
+    (this._surfaceWatchers ??= new Map()).set(id, fn);
+    return () => {
+      if (this._surfaceWatchers?.get(id) === fn) {
+        this._surfaceWatchers.delete(id);
+      }
+    };
   }
 
   _routeAccessibility(ev) {

package/src/cocoa/glarea.js

@@ -6,7 +6,8 @@
 // X server exported, frames render into IOSurface-backed framebuffers
 // (x11-dri `createTarget`) and present by handing the IOSurface's process-
 // global id to the area's own sublayer (`setLayerContentsIOSurface`). Two
-// targets alternate, like any swapchain; the WindowServer composites.
+// targets alternate, like any swapchain — three while a worker's flip has
+// yet to let go of the buffer it replaced; the WindowServer composites.
 //
 // What GlAreaNode needs from us is the child-"window" contract it already
 // speaks (src/glnodes.js): `createWindow({ parent, … })` answering an
@@ -33,6 +34,30 @@ import { withoutActions } from './quiet.js';
 const RUNGS = ['auto', 'gl'];
 const KNOWN_RUNGS = ['auto', 'gl', 'gles', 'webgpu'];
 
+/** Buffers a surface's chain may hold: the window presenter's
+ *  `MAX_BUFFERS`. A scene drawn at the display's rate takes all four, since
+ *  each buffer it retires is held for `HOLD_PERIODS` and a frame that
+ *  presents late in its period retires its buffer late too; with three it
+ *  waited for one, and a 120Hz scene ran at 80. */
+const MAX_BUFFERS = 4;
+/** How many display periods a buffer is taken to stay on glass after the
+ *  flip that replaced it: the render server latches a flip at a vsync a
+ *  period or two after the commit, and composites from the old buffer until
+ *  then. Two buffers alternating at the display's rate drew into the one it
+ *  was still reading — `IOSurfaceIsInUse` true at nine frames in ten — and
+ *  now and then it composited that buffer half drawn: the scene's clear
+ *  colour, over the whole surface, for a frame. A period was not enough
+ *  either (one frame in seven). The window presenter asks
+ *  `surfaceIsInUse`; these buffers are x11-dri's, which nothing asks yet. */
+const HOLD_PERIODS = 1.5;
+/** How long a worker's flip may take to report its release before the
+ *  buffer it retired is drawn into anyway — the window presenter's
+ *  `FENCE_TIMEOUT_MS`. */
+const RELEASE_TIMEOUT_MS = 100;
+/** A chain past two buffers gives the rest back after this long without a
+ *  frame — the window presenter's `TRIM_AFTER_MS`. */
+const TRIM_AFTER_MS = 1000;
+
 let driPromise = null;
 function loadDri() {
   if (!driPromise) {
@@ -292,6 +317,11 @@ export class CocoaGLArea {
 function createGLAreaContext(runtime, area, config) {
   const native = area._native;
   const ctx = Object.create(runtime.gl);
+  // The chain: every buffer this surface draws in, `{ target, released,
+  // offGlassAt, unwatch }`. `front` is the one the last swap put on glass,
+  // and `back` the one the frame being drawn goes into, from `makeCurrent`
+  // to `SwapBuffers`.
+  let buffers = [];
   let front = null;
   let back = null;
   let width = 0;
@@ -301,20 +331,89 @@ function createGLAreaContext(runtime, area, config) {
   // millisecond before its own timer still reads the true state.
   let gateOpenAt = -Infinity;
   let gateTimer = null;
+  let releaseTimer = null;
+  let trimTimer = null;
+  let swappedAt = -Infinity;
   let destroyed = false;
+  // The frame clock's time, which `canRender` is asked on and a hold is
+  // counted on: the window's clock hands out the slot a frame was due at,
+  // and a test drives it by hand. `skew` is how far it was from
+  // `performance.now()` when it was last asked.
+  let skew = 0;
+  const clock = () => performance.now() + skew;
+
+  const size = () => [
+    Math.max(1, area.rect?.width ?? 1),
+    Math.max(1, area.rect?.height ?? 1),
+  ];
+
+  const drop = (buffer) => {
+    buffer.unwatch?.();
+    buffer.target.destroy();
+  };
 
+  // A new size is a new chain, made a buffer at a time as frames take them.
+  // Nothing of the old one is drawn into again, so nothing waits for it.
   const ensureTargets = () => {
-    const w = Math.max(1, area.rect?.width ?? 1);
-    const h = Math.max(1, area.rect?.height ?? 1);
-    if (front && width === w && height === h) return;
-    front?.destroy();
-    back?.destroy();
-    front = runtime.ctx.createTarget(w, h);
-    back = runtime.ctx.createTarget(w, h);
+    const [w, h] = size();
+    if (width === w && height === h) return;
+    for (const buffer of buffers) drop(buffer);
+    buffers = [];
+    front = back = null;
     width = w;
     height = h;
   };
 
+  /**
+   * Of the buffers off glass, the one a frame may draw in now: one the
+   * flip that retired it has let go of, and of those the one off glass
+   * longest, which the WindowServer has had longest to stop reading.
+   * `'new'` while the chain has room for another. Past that, one whose
+   * release is overdue. Else null: the frame waits for a release.
+   */
+  const freeBuffer = (now) => {
+    const hold = runtime.frameInterval * HOLD_PERIODS;
+    let free = null;
+    let overdue = null;
+    for (const buffer of buffers) {
+      if (buffer === front) continue;
+      if (buffer.released && now - buffer.offGlassAt >= hold) {
+        if (!free || buffer.offGlassAt < free.offGlassAt) free = buffer;
+      } else if (now - buffer.offGlassAt >= RELEASE_TIMEOUT_MS) {
+        if (!overdue || buffer.offGlassAt < overdue.offGlassAt) {
+          overdue = buffer;
+        }
+      }
+    }
+    if (free) return free;
+    if (buffers.length < MAX_BUFFERS) return 'new';
+    return overdue;
+  };
+
+  const takeBack = () => {
+    const found = freeBuffer(clock());
+    if (found && found !== 'new') return found;
+    if (found === 'new') {
+      const buffer = {
+        target: runtime.ctx.createTarget(width, height),
+        released: true,
+        offGlassAt: -Infinity,
+        unwatch: null,
+      };
+      buffers.push(buffer);
+      return buffer;
+    }
+    // Asked to draw with nothing free — by a caller that did not ask
+    // `canRender` first: the buffer off glass longest, which is the one a
+    // chain of two always drew into.
+    let oldest = null;
+    for (const buffer of buffers) {
+      if (buffer === front) continue;
+      if (!oldest || buffer.offGlassAt < oldest.offGlassAt) oldest = buffer;
+    }
+    return oldest;
+  };
+
   ctx.backend = 'direct';
   ctx.config = config;
   ctx.glVersion = runtime.glVersion;
@@ -336,12 +435,30 @@ function createGLAreaContext(runtime, area, config) {
   // are on one grid: the clock cannot take a frame the gate would refuse,
   // because both are the same instant, and the gate still never lets two
   // frames into one period.
-  ctx.canRender = (now = performance.now()) => !destroyed && now >= gateOpenAt;
+  //
+  // And a period is not long enough to stay off the buffer the last flip
+  // retired: the render server latches a flip a period or two after it is
+  // committed, and reads the buffer it replaces until then — on a worker,
+  // where the flip waits for the UI thread, until later still. A frame
+  // drawn into it was now and then composited half drawn: the scene's
+  // clear colour over the whole surface, for a frame, as a map settled
+  // after a zoom. So a frame takes a buffer that has been off glass for
+  // `HOLD_PERIODS` and, on a worker, released (`freeBuffer`), and the gate
+  // is shut while there is none and no room in the chain for another.
+  ctx.canRender = (now = performance.now()) => {
+    skew = now - performance.now();
+    if (destroyed || now < gateOpenAt) return false;
+    const [w, h] = size();
+    if (back || width !== w || height !== h || freeBuffer(now)) return true;
+    armRelease();
+    return false;
+  };
 
   ctx.makeCurrent = () => {
     if (destroyed) return;
     ensureTargets();
-    runtime.ctx.bindTarget(back);
+    back ??= takeBack();
+    runtime.ctx.bindTarget(back.target);
   };
 
   // WebGL's "null means the default framebuffer" — and this surface's
@@ -349,7 +466,82 @@ function createGLAreaContext(runtime, area, config) {
   // a swapchain like this is nothing at all. A scene that renders through
   // its own FBO and unbinds at the end (the SSAA pattern) lands back here.
   ctx.bindFramebuffer = (target, fb) => {
-    runtime.gl.bindFramebuffer(target, fb == null ? (back?.fbo ?? 0) : fb);
+    runtime.gl.bindFramebuffer(
+      target,
+      fb == null ? (back?.target.fbo ?? 0) : fb,
+    );
+  };
+
+  /**
+   * The buffer a worker's flip just took off glass is held until the bridge
+   * says the flip applied (`surface-released`, windowkit/appkit#52) — the
+   * window presenter's fence, for this surface's own buffers. The flip
+   * happened then, so `HOLD_PERIODS` counts from then; a frame refused
+   * meanwhile is asked for again once that is over.
+   */
+  const awaitRelease = (buffer) => {
+    buffer.unwatch?.();
+    buffer.released = false;
+    buffer.unwatch = area.app.watchSurfaceRelease(
+      buffer.target.iosurfaceId,
+      () => {
+        buffer.unwatch = null;
+        buffer.released = true;
+        buffer.offGlassAt = clock();
+        if (!destroyed) armRelease();
+      },
+    );
+  };
+
+  // A frame refused for want of a buffer is asked for again when the first
+  // one frees: its hold over, or its release overdue — a release that
+  // never comes stops holding the frames after `RELEASE_TIMEOUT_MS`.
+  let releaseDue = Infinity;
+  const armRelease = () => {
+    if (destroyed) return;
+    const hold = runtime.frameInterval * HOLD_PERIODS;
+    let due = Infinity;
+    for (const buffer of buffers) {
+      if (buffer === front) continue;
+      const wait = buffer.released ? hold : RELEASE_TIMEOUT_MS;
+      due = Math.min(due, buffer.offGlassAt + wait);
+    }
+    if (due === Infinity || (releaseTimer && releaseDue <= due)) return;
+    if (releaseTimer) clearTimeout(releaseTimer);
+    releaseDue = due;
+    releaseTimer = setTimeout(
+      () => {
+        releaseTimer = null;
+        if (!destroyed) ctx.onFrameAvailable?.();
+      },
+      Math.max(1, Math.ceil(due - clock())),
+    );
+    releaseTimer.unref?.();
+  };
+
+  // A chain that grew past two gives the rest back once the surface has
+  // gone `TRIM_AFTER_MS` without a frame: the buffers past two are what a
+  // scene drawn at the display's rate needs, and a still one keeps what it
+  // always had, the buffer on glass and one to draw the next frame in.
+  const armTrim = () => {
+    if (trimTimer || destroyed) return;
+    trimTimer = setTimeout(() => {
+      trimTimer = null;
+      if (destroyed || buffers.length <= 2) return;
+      if (clock() - swappedAt < TRIM_AFTER_MS) {
+        armTrim();
+        return;
+      }
+      const spare = buffers
+        .filter((b) => b !== front && b !== back && b.released)
+        .sort((a, b) => a.offGlassAt - b.offGlassAt)
+        .slice(0, buffers.length - 2);
+      for (const buffer of spare) drop(buffer);
+      buffers = buffers.filter((b) => !spare.includes(b));
+      // one still held keeps its place until its release comes
+      if (buffers.length > 2) armTrim();
+    }, TRIM_AFTER_MS);
+    trimTimer.unref?.();
   };
 
   // A frame refused by the gate has nothing else to wake it, so the gate
@@ -375,26 +567,36 @@ function createGLAreaContext(runtime, area, config) {
   ctx.SwapBuffers = () => {
     if (destroyed || !back) return;
     runtime.gl.flush();
-    native.setLayerContentsIOSurface(area.layer, back.iosurfaceId);
-    const shown = back;
-    back = front;
-    front = shown;
+    native.setLayerContentsIOSurface(area.layer, back.target.iosurfaceId);
+    const retired = front;
+    front = back;
+    back = null;
+    swappedAt = clock();
+    if (retired && retired !== front) {
+      retired.offGlassAt = swappedAt;
+      // A pump-mode flip is applied in the call; a worker's when the UI
+      // thread gets to it, and until then `retired` is still on glass.
+      if (area.app._threaded) awaitRelease(retired);
+    }
     // one display period from the frame's slot, not from this moment
     gateOpenAt = area.nextFrameAt(runtime.frameInterval);
     armGate();
+    if (buffers.length > 2) armTrim();
   };
 
   ctx._resized = () => {
     // targets are rebuilt lazily on the next makeCurrent, so a resize
-    // storm costs two allocations per drawn frame, not per notify
+    // storm costs one allocation per drawn frame, not per notify
   };
 
   ctx._destroy = () => {
     if (destroyed) return;
     destroyed = true;
     if (gateTimer) clearTimeout(gateTimer);
-    front?.destroy();
-    back?.destroy();
+    if (releaseTimer) clearTimeout(releaseTimer);
+    if (trimTimer) clearTimeout(trimTimer);
+    for (const buffer of buffers) drop(buffer);
+    buffers = [];
     front = back = null;
   };
 

package/src/cocoa/overlay.js

@@ -19,6 +19,10 @@ import { BackendContext2D } from '../backend/context2d.js';
 import { withoutActions } from './quiet.js';
 
 export const OVERLAY_Z = 1e7 + 1;
+/** How far above the last each pane of a surface is stacked (`stackAt`): a
+ *  thousand of them stay under the next whole number, so above every GL
+ *  layer and every surface's panes above every GL frame, as before. */
+const OVERLAY_STEP = 1 / 1024;
 
 export class CocoaOverlayPane {
   constructor(app, options) {
@@ -43,6 +47,8 @@ export class CocoaOverlayPane {
     // show, only whatever the render server makes of that.
     this._presented = false;
     this._hidden = false;
+    // where it is among its surface's panes, a child each (`stackAt`)
+    this._z = OVERLAY_Z;
     this.setState({
       x: options.x ?? 0,
       y: options.y ?? 0,
@@ -66,11 +72,20 @@ export class CocoaOverlayPane {
     const s = this.scale;
     this._setLayerProps({
       frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
-      zPosition: OVERLAY_Z,
+      zPosition: this._z,
       hidden: this._hidden || !this._presented,
     });
   }
 
+  /** Stacked `index` panes up from the bottom of its surface's — one a
+   * child, in the children's order (src/gloverlay.js, `restack`). */
+  stackAt(index) {
+    const z = OVERLAY_Z + Math.min(index, 1023) * OVERLAY_STEP;
+    if (z === this._z) return;
+    this._z = z;
+    this._setLayerProps({ zPosition: z });
+  }
+
   map() {
     this._hidden = false;
     if (this._presented) this._setLayerProps({ hidden: false });

package/src/components/Select.js

@@ -329,6 +329,16 @@ function Option({
  * what a browser does with a `<select>` a page styled, and `false` keeps the
  * drawn one. A drawn trigger's menu is set at the caption's size, in the
  * family its style names when the system has it.
+ *
+ * `onOpenChange(open)` is told each time the menu goes down or comes up,
+ * the drawn one or the platform's, whatever moved it — the user, a pick,
+ * the trigger scrolling out of view, the platform's menu dismissing itself.
+ * `open` puts the menu in its owner's hands, as `value` puts the option:
+ * the menu drops when it goes `true` and comes up when it goes `false`, and
+ * what the user does to open or close it asks `onOpenChange` instead of
+ * doing it. A menu that cannot drop — a trigger not in a window — or that
+ * goes by itself is told as `false`, so an owner that keeps what it is told
+ * keeps what is on screen. Left out, the select keeps its own.
  */
 export function Select({
   value,
@@ -338,6 +348,8 @@ export function Select({
   placeholder = 'Select…',
   native,
   nativeMenu,
+  open: openProp,
+  onOpenChange,
   style,
   labelStyle,
   chevronStyle,
@@ -444,7 +456,8 @@ export function Select({
   const openPlatformMenu = () => {
     const node = triggerRef.current;
     const wnd = node?.root?.window;
-    if (!node || !wnd || platformRef.current) return;
+    if (platformRef.current) return true;
+    if (!node || !wnd) return false;
     const chosen = normalized.findIndex((o) => o.value === value);
     const family = menuFamily(flattenStyle(labelStyle).fontFamily);
     setPlatformOpen(true);
@@ -471,22 +484,64 @@ export function Select({
         if (option && option.value !== value) emit(option.value);
       },
     );
+    return true;
   };
+  /** Drop the menu, whichever it is; whether it is down. */
   const openMenu = () => {
-    if (platformMenu) {
-      openPlatformMenu();
-      return;
-    }
+    if (platformMenu) return openPlatformMenu();
     const node = triggerRef.current;
-    if (!node) return;
+    if (!node) return false;
     const rect = measureAnchor(menuAnchorOptions());
-    if (!rect) return;
+    if (!rect) return false;
     setAnchor(rect);
     const selected = normalized.findIndex((o) => o.value === value);
     setActiveIndex(selected >= 0 ? selected : 0);
     setOpen(true);
+    return true;
+  };
+
+  // Whether the menu is down is the select's own, or with `open` its
+  // owner's. `told` is what the owner knows: what it last said through
+  // `open`, or what it was last told through `onOpenChange` — so each
+  // change is told once, and one the owner made itself is not told back.
+  const controlled = openProp !== undefined;
+  const told = useRef(false);
+  const said = useRef(false);
+  const openChange = useRef(onOpenChange);
+  openChange.current = onOpenChange;
+  const tell = (next) => {
+    if (told.current === next) return;
+    told.current = next;
+    openChange.current?.(next);
+  };
+  /** What the user, or the menu's own dismissal, asks for: done, or with
+   *  `open` asked of the owner. */
+  const ask = (next) => {
+    if (!controlled) {
+      if (next) openMenu();
+      else close();
+      return;
+    }
+    tell(next);
   };
-  const toggle = () => (expanded ? close() : openMenu());
+  // The menu follows what the owner says as it changes, and what it comes
+  // to is told: down, up, or up again by itself. One effect does both: in
+  // two, the pass in which `open` changed told the owner back the state
+  // from before the change, which the menu had not followed yet.
+  useEffect(() => {
+    if (controlled && openProp !== said.current) {
+      said.current = openProp;
+      told.current = openProp;
+      if (openProp && !expanded) {
+        if (!openMenu()) tell(false);
+      } else if (!openProp && expanded) close();
+      return;
+    }
+    tell(expanded);
+  }, [controlled, openProp, expanded]);
+
+  const toggle = () => ask(!expanded);
+  const dismiss = () => ask(false);
   // a menu still down when the select goes is taken with it
   useEffect(() => () => platformRef.current?.(), []);
 
@@ -498,15 +553,15 @@ export function Select({
   // following it there — a popup is a real window, not something clipped
   // by the trigger's ancestors, so it would otherwise hang over content it
   // no longer points at.
-  useAnchorTracking(triggerRef, open, menuAnchorOptions, setAnchor, close);
+  useAnchorTracking(triggerRef, open, menuAnchorOptions, setAnchor, dismiss);
   // and shut it when the whole window loses focus: the trigger keeps the
   // focus it has, so its own `onBlur` never fires for this
-  useDismissOnWindowBlur(triggerRef, open, close);
+  useDismissOnWindowBlur(triggerRef, open, dismiss);
 
   const emit = (next) => onChange?.(changeEvent('select-one', name, next));
 
   const pick = (option) => {
-    close();
+    dismiss();
     if (option.value !== value) emit(option.value);
   };
 
@@ -520,12 +575,12 @@ export function Select({
     const count = normalized.length;
     switch (ev.keysym) {
       case XK_ESCAPE:
-        if (open) close();
+        if (open) dismiss();
         return;
       case XK_DOWN:
       case XK_UP:
         if (open) move(ev.keysym === XK_DOWN ? 1 : -1);
-        else openMenu();
+        else ask(true);
         return;
       case XK_HOME:
       case XK_END:
@@ -589,7 +644,7 @@ export function Select({
       onFocus: () => setFocused(true),
       onBlur: () => {
         setFocused(false);
-        close();
+        dismiss();
       },
       onKeyDown,
       ...boxProps,
@@ -721,7 +776,7 @@ export function Select({
           // control, not the bare `<popup>` default of `popup_menu`
           windowType: 'dropdown_menu',
           grab: true,
-          onDismiss: close,
+          onDismiss: dismiss,
           // ARGB where the display has it, so the corners the sheet gives up
           // are the desktop rather than a colour — as the menus are. The
           // window paints nothing itself when it can be seen through: the

package/src/events.js

@@ -2040,6 +2040,13 @@ export class EventManager {
    * Asks `isScroller()` rather than whether the method exists: every `<box>`
    * carries `scrollIntoView` now, and one that is not a scroll container
    * would end the walk without revealing anything.
+   *
+   * And it ends at the node's window. A `<popup>` hangs off a node of its
+   * owner's tree, but it is a window of its own on the screen: no pane in
+   * the owner scrolls it, and the pane above it measured the popup's
+   * content as if it were laid out at the popup's parent — so the edit
+   * menu, focusing its rows, scrolled a document in a pane to its top on
+   * every right-click.
    */
   _scrollIntoView(node) {
     for (let n = node.parent; n; n = n.parent) {
@@ -2047,6 +2054,7 @@ export class EventManager {
         n.scrollIntoView(node);
         return;
       }
+      if (n.isWindow) return;
     }
   }
 

package/src/frame/index.js

@@ -696,11 +696,19 @@ function PaneHostView({
     const node = containerRef.current;
     if (!s || !node) return;
     const sc = node.scale ?? 1;
+    // Where the pointer is on the screen, which is what `rootx`/`rooty` are
+    // on every backend, and what a `<ContextMenu>` in the pane opens its
+    // popup at (`openAt`, components/Menu.js). The window's origin plus the
+    // window point: the same sum the pane is told its own corner by
+    // (`syncSize` below), so the pane's `x` plus its corner is this. Sent
+    // the window point, a pane's menu opened up and to the left of the
+    // pointer by as far as the window was from the screen's corner.
+    const origin = node.root?.window?._screenOrigin ?? { x: 0, y: 0 };
     const payload = {
       x: Math.max(0, Math.round(ev.x * sc - node.abs.x)),
       y: Math.max(0, Math.round(ev.y * sc - node.abs.y)),
-      rootx: Math.round(ev.x * sc),
-      rooty: Math.round(ev.y * sc),
+      rootx: Math.round(origin.x + ev.x * sc),
+      rooty: Math.round(origin.y + ev.y * sc),
       // The modifier mask, which a synthetic event carries on its native
       // event alone. Read off the synthetic one, every key and press
       // reached the pane with none: Shift+Tab went forwards there, and a

package/src/gloverlay.js

@@ -17,10 +17,18 @@
 // translucent child over a GL surface?
 //
 // - **The Cocoa backend: yes.** Core Animation composites every layer, so
-//   one pane holds everything — a transparent bitmap layer over the whole
-//   surface, above the GL layer — and a translucent background, an
-//   antialiased edge or a shadow blends with the GL frame under it.
-//   `app.createOverlayPane` is how a backend says it composites.
+//   a pane is a transparent bitmap layer above the GL layer, and a
+//   translucent background, an antialiased edge or a shadow blends with the
+//   GL frame under it. `app.createOverlayPane` is how a backend says it
+//   composites. Where it can stack its panes as well
+//   (`app.overlaysPerChild`), a pane is one per child, as on X11, holding
+//   that child alone — the layers under it show through — and as big as
+//   what the child reaches: a layer's contents are a copy of its bitmap,
+//   colour-matched to the display as it is pushed, and one the size of the
+//   surface pushed again at every step a minimap's viewport moved was a
+//   quarter of a core on a Mac. A child that only moved moves its layer,
+//   and nothing is painted. Otherwise one pane holds every child, over the
+//   whole surface.
 // - **X11: no.** A child window is opaque without a compositor, and a
 //   compositor would not change that: it redirects top-level windows, not
 //   the children inside one. So a pane is a plain child window just big
@@ -746,8 +754,9 @@ function askShape(app) {
  */
 class Pane {
   /**
-   * @param node the child an X11 pane is kept by and holds, up to — null for
-   *   a composited pane, which holds every child
+   * @param node the child a pane is kept by and holds — up to it on X11,
+   *   alone where it is composited — and null for a composited pane over
+   *   the whole surface, which holds every child
    * @param overlay the panes it is one of, which `canBlit` asks about
    */
   constructor(wnd, rect, transparent, node = null, overlay = null) {
@@ -842,7 +851,8 @@ class Pane {
     };
     if (!this.wnd.scrollRegion(local, dx, dy)) return false;
     this.blitted = true;
-    const panes = this.node ? this.overlay?.panes : null;
+    // composited, a pane over it holds none of it
+    const panes = this.node && !this.transparent ? this.overlay?.panes : null;
     if (panes) {
       for (let i = panes.indexOf(this) + 1; i < panes.length; i++) {
         panes[i].owe(rect);
@@ -867,8 +877,11 @@ export class GlOverlay {
   constructor(area) {
     this.area = area;
     this.app = area.app;
-    // one pane over the whole surface, where the backend composites it
+    // panes the backend composites, transparent, rather than child windows
     this.composited = typeof this.app?.createOverlayPane === 'function';
+    // a pane a child: X11's, and a compositor's that stacks its panes; one
+    // pane over the whole surface elsewhere
+    this.perChild = !this.composited || this.app?.overlaysPerChild === true;
     // bottom to top: the children's order on X11, one pane each
     this.panes = [];
     // X11: each child's pane, kept by the child for as long as it has one
@@ -908,7 +921,7 @@ export class GlOverlay {
     const visible = shown(area) && abs.width > 0 && abs.height > 0;
     // the surface's own rect, rounded the way its window's is
     const surface = visible ? area._geometry() : null;
-    if (!this.composited) return this._syncChildren(surface);
+    if (this.perChild) return this._syncChildren(surface);
     const rects = surface && area.paintOrder().length ? [surface] : [];
     let changed = false;
     while (this.panes.length > rects.length) {
@@ -929,13 +942,14 @@ export class GlOverlay {
   }
 
   /**
-   * `sync` on X11: a pane per child, kept by the child. A child that is new
-   * gets one, a child that went takes its with it, and one whose reach moved
-   * has its pane placed there — and painted whole, unless the move was the
-   * child's own and nothing else, which the window's move carries
-   * (`_settleMove` repaints what it does not). A change of order restacks
-   * them, and repaints whichever overlap another: what a pane holds is what
-   * is under its child.
+   * `sync` on X11, and where panes composite a child each: a pane per
+   * child, kept by the child. A child that is new gets one, a child that
+   * went takes its with it, and one whose reach moved has its pane placed
+   * there — and painted whole, unless the move was the child's own and
+   * nothing else, which the window's move carries (`_settleMove` repaints
+   * what it does not). A change of order restacks them, and on X11 repaints
+   * whichever overlap another: what an X11 pane holds is what is under its
+   * child.
    */
   _syncChildren(surface) {
     const regions = surface ? childRegions(this.area, surface) : [];
@@ -981,9 +995,10 @@ export class GlOverlay {
     this.panes = next;
     if (reordered) {
       this.restack();
-      if (!made) {
+      if (!made && !this.composited) {
         // what each pane holds is its child and what is under it: a new
-        // order is new contents wherever two of them meet
+        // order is new contents wherever two of them meet — on X11, where a
+        // pane is opaque; a composited one holds its child alone
         for (const pane of next) {
           if (
             next.some(
@@ -1041,7 +1056,11 @@ export class GlOverlay {
    * Cocoa backend the layer's zPosition is the whole of it.
    */
   restack() {
-    if (this.composited) return;
+    if (this.composited) {
+      // a composited pane a child is stacked by the backend, in order
+      this.panes.forEach((pane, i) => pane.wnd.stackAt?.(i));
+      return;
+    }
     const X = this.app?.X;
     if (typeof X?.ConfigureWindow !== 'function') return;
     let below = this.area.window?.id ?? null;
@@ -1085,7 +1104,7 @@ export class GlOverlay {
     if (!root || root.destroyed || root._paneDamage === FULL_DAMAGE) {
       return true;
     }
-    if (!this.composited) {
+    if (this.perChild) {
       // Each child's move is its own pane's to settle: carried by the
       // window's move where its pane went with it, moved on the pane where
       // the pane stayed — cut to the surface, say, which a box bigger than
@@ -1135,6 +1154,9 @@ export class GlOverlay {
    * - The panes under it hold nothing of it, and are owed nothing.
    */
   _settleCarried({ node, reach, dx, dy }, reaches) {
+    // a composited pane holds its child alone, and the layer's move carried
+    // all of it: nothing is owed anywhere
+    if (this.composited) return;
     const panes = this.panes;
     const at = panes.indexOf(this.byNode.get(node));
     const own = panes[at];
@@ -1231,10 +1253,15 @@ export class GlOverlay {
     for (const piece of outside(was, dest)) add(piece);
     if (now) for (const piece of outside(now, dest)) add(piece);
     // the children whose pixels the pane holds: every other one on a pane
-    // over the whole surface, and on X11 the ones under this child — the
-    // panes over it are owed the copy by `Pane.blit`
+    // over the whole surface, on X11 the ones under this child — the panes
+    // over it are owed the copy by `Pane.blit` — and none on a composited
+    // pane a child
     const order = area.paintOrder();
-    const upTo = own ? order.indexOf(node) : order.length;
+    const upTo = !own
+      ? order.length
+      : this.composited
+        ? 0
+        : order.indexOf(node);
     for (let i = 0; i < upTo; i++) {
       const other = order[i];
       if (other === node) continue;
@@ -1324,8 +1351,13 @@ export class GlOverlay {
         }
         root._paintDamage = pass;
         // an X11 pane holds its child and what is under it, and never
-        // what is over it — the pane over it holds that (see the header)
-        area._paintChildren(ctx, pane.node);
+        // what is over it — the pane over it holds that (see the header);
+        // a composited pane a child holds its child alone
+        area._paintChildren(
+          ctx,
+          pane.node,
+          pane.transparent && pane.node !== null,
+        );
       } finally {
         root._paintDamage = null;
         ctx.restore();

package/src/nodes/fieldselection.js

@@ -0,0 +1,132 @@
+// A field's selection, read and set from outside it: `selectionStart`,
+// `selectionEnd`, `selectionDirection`, `setSelectionRange()` and
+// `select()`, the DOM's names on the node, for <textinput> and <textarea>
+// alike. What a copy-link box, a search field that selects on focus, an
+// input mask or an emoji picker does through a DOM input's, an application
+// does through the ref — and `@react-x11/components`' `<Html>` does for the
+// page's scripts, on the field it mounts for an `<input>`.
+//
+// Two things here are decisions rather than accidents.
+//
+// **The offsets are UTF-16 code units**, as the DOM's are, where the rest of
+// the field counts code points (textrange.js). Code that reads them slices
+// `value` with them — `value.slice(selectionStart, selectionEnd)` is what is
+// selected, `value.slice(0, start) + emoji + value.slice(end)` is an insert
+// at the caret — and a JavaScript string is indexed in code units, so an
+// offset in code points is one short for every emoji before it. An offset
+// that falls between the two halves of a surrogate pair is taken to the
+// character's start, as `codePointAtOffset` rounds.
+//
+// **A selection set from outside is not the user's.** It is the field's
+// selection in every way an edit can tell — it is drawn while the field has
+// the focus, Backspace deletes it, typing replaces it, Shift+arrow extends
+// it — but it does not take PRIMARY. On X11 PRIMARY is what the user last
+// selected, for a middle-click to paste somewhere else, and a field that a
+// script selects on focus would otherwise replace it every time it is
+// tabbed into, with a timestamp no user event gave (ICCCM 2.1). It does
+// take the visible selection, where it is drawn: one lit range on screen at
+// a time (textselection.js).
+
+import { codePointAtOffset, codeUnitOffsets } from '../textrange.js';
+import { takeVisibleSelection } from '../textselection.js';
+
+/** The selection API, installed onto `TextInputNode.prototype` by
+ * textinput.js. */
+export class TextInputSelection {
+  /** The offset, in UTF-16 code units, where the selection starts — the
+   * caret's, where nothing is selected. */
+  get selectionStart() {
+    return this._unitOffset(this._selection()[0]);
+  }
+
+  /** As the DOM's: the end moves with the start where the start passes it. */
+  set selectionStart(start) {
+    const at = this._clampUnits(start);
+    this.setSelectionRange(
+      at,
+      Math.max(at, this.selectionEnd),
+      this.selectionDirection,
+    );
+  }
+
+  /** The offset, in UTF-16 code units, where the selection ends. */
+  get selectionEnd() {
+    return this._unitOffset(this._selection()[1]);
+  }
+
+  /** As the DOM's: the start moves back to the end where the end is put
+   * before it. */
+  set selectionEnd(end) {
+    this.setSelectionRange(
+      this.selectionStart,
+      this._clampUnits(end),
+      this.selectionDirection,
+    );
+  }
+
+  /**
+   * Which end the caret is at: `'backward'` where it is at the start,
+   * `'forward'` where it is at the end, and `'none'` for a bare caret. A
+   * direction set through `setSelectionRange` reads back as it was set —
+   * `'none'` included, over a range — until the user moves either end.
+   */
+  get selectionDirection() {
+    const set = this._directionSet;
+    if (set && set.caret === this._caret && set.anchor === this._anchor) {
+      return set.direction;
+    }
+    if (this._caret < this._anchor) return 'backward';
+    if (this._caret > this._anchor) return 'forward';
+    return 'none';
+  }
+
+  set selectionDirection(direction) {
+    this.setSelectionRange(this.selectionStart, this.selectionEnd, direction);
+  }
+
+  /**
+   * Select `[start, end)`, in UTF-16 code units, as a DOM input's
+   * `setSelectionRange` does: each end clamped to the value, a start past
+   * the end moved back to it, and the caret at the end — or, for
+   * `'backward'`, at the start, so Shift+Left goes on from there. Equal
+   * offsets put a bare caret. An open composition is left where it is.
+   */
+  setSelectionRange(start, end, direction = 'none') {
+    const to = this._clampUnits(end);
+    const from = Math.min(this._clampUnits(start), to);
+    const offsets = codeUnitOffsets(this.value);
+    const a = codePointAtOffset(offsets, from);
+    const b = codePointAtOffset(offsets, to);
+    const backward = direction === 'backward';
+    this._anchor = backward ? b : a;
+    this._caret = backward ? a : b;
+    this._directionSet = {
+      direction: backward || direction === 'forward' ? direction : 'none',
+      caret: this._caret,
+      anchor: this._anchor,
+    };
+    // typing that resumes at the new caret is a new edit, as after a click
+    this._breakUndoRun();
+    if (a !== b && this._focused) takeVisibleSelection(this);
+    this._repaint();
+  }
+
+  /** Select the whole value, as a DOM input's `select()` does. */
+  select() {
+    this.setSelectionRange(0, this.value.length);
+  }
+
+  /** A code-point index in the value as a UTF-16 offset. */
+  _unitOffset(index) {
+    const offsets = codeUnitOffsets(this.value);
+    return offsets[Math.min(Math.max(0, index), offsets.length - 1)];
+  }
+
+  /** A UTF-16 offset from outside, as a whole number inside the value:
+   * NaN is 0, a fraction is cut, and either side of the value is its end. */
+  _clampUnits(offset) {
+    const n = Math.trunc(Number(offset));
+    if (Number.isNaN(n)) return 0;
+    return Math.min(Math.max(0, n), this.value.length);
+  }
+}

package/src/nodes/paint.js

@@ -337,9 +337,10 @@ export class NodePaint {
   /**
    * The children, in paint order — or those up to and including `upTo`: an
    * X11 pane over a `<glarea>` holds its own child and what is under it,
-   * never what is over it (src/gloverlay.js, `_paintPane`).
+   * never what is over it (src/gloverlay.js, `_paintPane`) — or `upTo` alone
+   * (`only`), which a composited pane a child holds.
    */
-  _paintChildren(ctx, upTo = null) {
+  _paintChildren(ctx, upTo = null, only = false) {
     // A retained presenter replays a node's `paint` into a visual of that
     // node's own — its children have visuals of their own, so it sets this
     // for the duration of the call (src/cocoa/presenter.js, `paintSelf`).
@@ -348,7 +349,7 @@ export class NodePaint {
     let order = this.paintOrder();
     if (upTo !== null) {
       const at = order.indexOf(upTo);
-      if (at !== -1) order = order.slice(0, at + 1);
+      if (at !== -1) order = only ? [upTo] : order.slice(0, at + 1);
     }
     if (order.length === 0) return;
     if (!this.clipsChildren()) {

package/src/nodes/textarea.js

@@ -178,6 +178,12 @@ export class TextAreaNode extends TextInputNode {
     super._applyHistory(value, caret, anchor);
   }
 
+  /** Nor does it once the caret is put somewhere from outside. */
+  setSelectionRange(start, end, direction) {
+    this._goalX = null;
+    super.setSelectionRange(start, end, direction);
+  }
+
   /** Wrapped, styled layout of the value (or placeholder), cached per
    * (text, style, width). Used for painting and all caret geometry, so
    * caret math always agrees with what is on screen. */

package/src/nodes/textinput.js

@@ -1,7 +1,8 @@
 // <textinput>: a single-line editable field — value, caret and selection,
 // the keys, the mouse, the clipboard, the edit menu and painting. Undo/redo
-// is in edithistory.js, IME composition in preedit.js and the Mac's editing
-// keys in textkeys.js, installed below.
+// is in edithistory.js, IME composition in preedit.js, the Mac's editing
+// keys in textkeys.js and the selection as the DOM reads and sets it in
+// fieldselection.js, installed below.
 
 import { localTextStyleChanged } from '../styles.js';
 import { Yoga } from '../yoga.js';
@@ -30,6 +31,7 @@ import { takeVisibleSelection } from '../textselection.js';
 import { TextInputHistory } from './edithistory.js';
 import { openEditMenu, editMenuOpen } from './editmenupopup.js';
 import { installMethods } from './install.js';
+import { TextInputSelection } from './fieldselection.js';
 import { Node } from './node.js';
 import { TextInputPreedit } from './preedit.js';
 import { rangeBands } from './text.js';
@@ -964,6 +966,10 @@ export class TextInputNode extends Node {
   defaultFocus() {
     this._focused = true;
     this._caretOn = true;
+    // A selection the field kept while it had no focus — one set from
+    // outside (`setSelectionRange`) — is drawn from now on, and is the one
+    // lit range on screen, as one the user drags here is.
+    if (this._caret !== this._anchor) takeVisibleSelection(this);
     // The desktop's cadence, read at focus rather than at import: XSETTINGS
     // is started but not awaited by createRoot, so this is the first moment
     // it is reliably in — and a field focused before that gets the default
@@ -1165,10 +1171,12 @@ export class TextInputNode extends Node {
   }
 }
 
-// Undo/redo and IME composition live in their own files (see install.js).
+// Undo/redo, IME composition, the Mac's keys and the selection API live in
+// their own files (see install.js).
 installMethods(
   TextInputNode,
   TextInputHistory,
   TextInputPreedit,
   TextInputKeys,
+  TextInputSelection,
 );

package/src/types/components.d.ts

@@ -545,6 +545,23 @@ export interface SelectProps<T = unknown>
    * Ignored where the backend has no such menu.
    */
   nativeMenu?: boolean;
+  /**
+   * Whether the menu is down, held by the owner as `value` holds the
+   * option: it drops when this goes `true` and comes up when it goes
+   * `false`, and what the user does to open or close it — a press, a key,
+   * a pick, a click outside — asks {@link SelectProps.onOpenChange} instead
+   * of doing it. Left out, the select keeps its own.
+   */
+  open?: boolean;
+  /**
+   * Told each time the menu goes down or comes up, the drawn one or the
+   * platform's, and with `open` asked when the user would move it. A menu
+   * that cannot drop — its trigger in no window — or that goes by itself,
+   * the platform's dismissing itself or the trigger scrolling out of view,
+   * is told as `false`. A change the owner made through `open` is not told
+   * back.
+   */
+  onOpenChange?: (open: boolean) => void;
 }
 export function Select<T = unknown>(props: SelectProps<T>): ReactNode;
 

package/src/types/nodes.d.ts

@@ -200,8 +200,43 @@ export interface TextInputNode extends DrawnNode {
   redo(): boolean;
   readonly canUndo: boolean;
   readonly canRedo: boolean;
+  /**
+   * Where the selection starts, as a DOM input's `selectionStart` says it:
+   * an offset into `value` in **UTF-16 code units**, so `value.slice(
+   * selectionStart, selectionEnd)` is the selected text. The caret's, where
+   * nothing is selected. Setting it moves the end with it where it passes
+   * the end.
+   */
+  selectionStart: number;
+  /** Where the selection ends, in UTF-16 code units. Setting it before the
+   * start moves the start back to it. */
+  selectionEnd: number;
+  /**
+   * Which end the caret is at: `'backward'` at the start, `'forward'` at the
+   * end, `'none'` for a bare caret — or as `setSelectionRange` set it, until
+   * the user moves either end.
+   */
+  selectionDirection: TextSelectionDirection;
+  /**
+   * Select `[start, end)`, in UTF-16 code units, as a DOM input's
+   * `setSelectionRange` does: clamped to the value, a start past the end
+   * moved back to it, the caret at the end or, for `'backward'`, at the
+   * start. Equal offsets put a bare caret there. Drawn while the field has
+   * the focus, and edited as the user's own selection is; it does not take
+   * PRIMARY, which is the user's last selection.
+   */
+  setSelectionRange(
+    start: number,
+    end: number,
+    direction?: TextSelectionDirection,
+  ): void;
+  /** Select the whole value, as a DOM input's `select()` does. */
+  select(): void;
 }
 
+/** A field's `selectionDirection`, as the DOM names it. */
+export type TextSelectionDirection = 'forward' | 'backward' | 'none';
+
 /**
  * ntk's `Window`, as handed back by a `<window>` or `<popup>` ref. This
  * covers what a react-x11 program usually reaches for; ntk has more (see