react-x11 2.29.0 → 2.30.0

package/package.json

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

package/src/cocoa/app.js

@@ -34,7 +34,7 @@ import { CocoaCalendars } from './calendar.js';
 import { CocoaNotifications } from './notifications.js';
 import { CocoaPaneHost } from './panehost.js';
 import { CocoaPermissions } from './permissions.js';
-import { CocoaPaneWindow } from './panewindow.js';
+import { CocoaPaneSubwindow, CocoaPaneWindow } from './panewindow.js';
 import { CocoaColorSampler } from './screencolor.js';
 import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
@@ -331,6 +331,11 @@ export class CocoaApp {
     // composites (REACT_X11_FRAME is what the Frame host sets on the fork).
     this._paneMode = options.pane ?? process.env.REACT_X11_FRAME === '1';
     this._paneSend = null;
+    // the pane's own window, the one the host lays out and forwards to
+    this._paneWindow = null;
+    // What the pane's other windows said before the host was listening
+    // (`_postWindow`), until its first pane-rect.
+    this._paneOutbox = [];
 
     // The X stub: just enough for the modules that carry an X escape hatch
     // to no-op the way they do against the headless mock.
@@ -447,7 +452,18 @@ export class CocoaApp {
     // shared IOSurfaces and the HOST composites them (src/cocoa/
     // panewindow.js). Chosen by the same prop the X11 pane uses.
     if (this._paneMode && attributes.embeddable) {
-      return new CocoaPaneWindow(this, attributes);
+      const wnd = new CocoaPaneWindow(this, attributes);
+      if (!this._paneWindow || this._paneWindow.destroyed) {
+        this._paneWindow = wnd;
+      }
+      return wnd;
+    }
+    // Any other window a pane makes — a menu, a tooltip, a dialog — is
+    // drawn here and shown by the host, which has the NSApplication this
+    // process does not (#824). An NSWindow made here exists and is never on
+    // glass.
+    if (this._paneMode && !attributes.parent) {
+      return new CocoaPaneSubwindow(this, attributes);
     }
     if (attributes.parent) {
       // A parented "window" here is a GL child surface — GlAreaNode's
@@ -487,10 +503,88 @@ export class CocoaApp {
   /**
    * 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-
-   * memory pane path instead of the X foreign-window embed.
+   * memory pane path instead of the X foreign-window embed. `send` is the
+   * pane's channel, for the windows the pane makes besides its own: a pane
+   * process runs no AppKit, so they are made here (src/cocoa/panehost.js).
    */
-  createPaneHost(wnd) {
-    return new CocoaPaneHost(this, wnd);
+  createPaneHost(wnd, { send } = {}) {
+    return new CocoaPaneHost(this, wnd, { send });
+  }
+
+  /**
+   * Whether this backend drops a control's menu as the platform's own — a
+   * bridge with `popUpMenu` (@windowkit/appkit 0.20) — rather than a drawn
+   * `<popup>` sized as one. What `<Select>` asks before it opens.
+   */
+  get nativePopUpMenus() {
+    return typeof this._native?.popUpMenu === 'function';
+  }
+
+  /**
+   * The platform's own menu, dropped from a control in one of this app's
+   * windows as an NSPopUpButton's drops: the item `spec.selected` placed
+   * over `spec.frame` and checked, the menu at least the frame's width.
+   * `spec` is the bridge's (`items`, `selected`, `fontSize`, `fontFamily`,
+   * `appearance`, `rtl`) with `frame` in the window's device pixels, which
+   * every rect on this side is. `onAnswer(id | null)` hears the item chosen,
+   * or null for a menu dismissed, once; the frame that answer causes goes
+   * out with it. Returns a function that cancels the menu.
+   *
+   * Opened on a microtask, after the input that asked for it has been
+   * answered and painted: in pump mode the menu's tracking holds this thread
+   * from the call to the choice, and the press that opened it should be on
+   * glass before it does. From a worker the call returns at once.
+   *
+   * A pane has no NSWindow to drop it from, so in a pane the host does,
+   * over the pane's place in its window (`CocoaPaneHost.popUpMenu`).
+   */
+  popUpMenu(wnd, spec, onAnswer) {
+    let answered = false;
+    const answer = (id) => {
+      if (answered) return;
+      answered = true;
+      onAnswer(id ?? null);
+      this._afterInput();
+    };
+    if (this._paneMode) return this._paneMenu(wnd, spec, answer);
+    let cancelled = false;
+    let handle = null;
+    queueMicrotask(() => {
+      if (cancelled || this._closed || !wnd || wnd.destroyed) {
+        answer(null);
+        return;
+      }
+      const s = wnd.scale ?? this.scale;
+      handle = this._native.popUpMenu(
+        wnd._h,
+        { ...spec, frame: spec.frame.map((v) => v / s) },
+        (id) => answer(id),
+      );
+    });
+    return () => {
+      if (answered) return;
+      cancelled = true;
+      if (handle) this._native.cancelPopUpMenu?.(handle);
+    };
+  }
+
+  /** A pane's menu, asked of the host: `pane-menu` with the frame in the
+   *  window it is in, `pane-menu-answer` back. */
+  _paneMenu(wnd, spec, answer) {
+    const menu = (this._paneMenuSeq = (this._paneMenuSeq ?? 0) + 1);
+    (this._paneMenus ??= new Map()).set(menu, answer);
+    this._paneSend?.({
+      type: 'pane-menu',
+      menu,
+      // the pane's own window is the one the host knows as the pane
+      ...(wnd && wnd !== this._paneWindow && { window: wnd.windowId }),
+      spec,
+    });
+    return () => {
+      if (this._paneMenus?.has(menu)) {
+        this._paneSend?.({ type: 'pane-menu-cancel', menu });
+      }
+    };
   }
 
   /**
@@ -780,18 +874,72 @@ export class CocoaApp {
       }
     };
     channel.onMessage((msg) => {
-      const wnd = [...this._windows.values()][0];
-      if (!wnd) return;
+      const pane = this._paneWindow ?? [...this._windows.values()][0];
+      if (!pane) return;
       if (msg?.type === 'pane-rect') {
-        wnd.setPaneSize(msg.width, msg.height, msg.scale);
+        pane.setPaneSize(msg.width, msg.height, msg.scale, msg.screen);
+        this._flushPaneOutbox();
         this._afterInput();
+      } else if (msg?.type === 'pane-menu-answer') {
+        const answer = this._paneMenus?.get(msg.menu);
+        this._paneMenus?.delete(msg.menu);
+        answer?.(msg.id ?? null);
       } else if (msg?.type === 'pane-event') {
-        wnd.emit(msg.name, msg.ev);
+        // input on one of the windows the host shows for this pane names
+        // it; the pane's own is the one that names none
+        const wnd = msg.window != null ? this._windows.get(msg.window) : pane;
+        if (!wnd || wnd.destroyed) return;
+        if (msg.name === 'resize') wnd._hostGeometry?.(msg.ev);
+        // a close request answers with `preventDefault`, which did not
+        // survive the channel
+        else if (msg.name === 'close')
+          wnd.emit('close', { ...msg.ev, preventDefault() {} });
+        else wnd.emit(msg.name, msg.ev);
         this._afterInput();
       }
     });
   }
 
+  /**
+   * A message about one of the pane's other windows (`CocoaPaneSubwindow`),
+   * held until the host's first pane-rect. The host hears a pane's messages
+   * from the moment it has a `<Frame>`, and knows what to do with these
+   * only once the pane is laid out in it — a menu or a dialog open in the
+   * pane's first commit was made, and announced to nobody. That pane-rect
+   * is also where the pane learns where it is on the screen, so a popup
+   * anchored before it is placed again before anyone shows it.
+   */
+  _postWindow(msg) {
+    if (this._paneOutbox) this._paneOutbox.push(msg);
+    else this._paneSend?.(msg);
+  }
+
+  /**
+   * The host is listening, and the pane knows where it is — `setPaneSize`
+   * has just moved what is anchored to it. Everything held goes out in
+   * order, but a window is announced where it is now: a held move or resize
+   * is where it was before, and sent in order it came after a present the
+   * host showed at the old place.
+   */
+  _flushPaneOutbox() {
+    const held = this._paneOutbox;
+    if (!held) return;
+    this._paneOutbox = null;
+    for (const msg of held) {
+      if (msg.type === 'pane-window') {
+        if (msg.op === 'move' || msg.op === 'resize') continue;
+        const wnd = msg.op === 'create' && this._windows.get(msg.window);
+        if (wnd) {
+          msg.x = wnd.x;
+          msg.y = wnd.y;
+          msg.width = wnd.width;
+          msg.height = wnd.height;
+        }
+      }
+      this._paneSend(msg);
+    }
+  }
+
   _unregisterWindow(wnd) {
     this._windows.delete(wnd._key);
     if (this._grabWindow === wnd) this._grabWindow = null;

package/src/cocoa/panehost.js

@@ -3,9 +3,16 @@
 // contents are whatever IOSurface the pane process last presented. The pane
 // owns its buffers and its drawing; this side owns the layer, the layout
 // and the input — CPU offloading, not isolation (docs/frame.md).
+//
+// And the windows the pane makes besides its own — a menu, a dropdown's
+// sheet, a tooltip, a dialog. A pane process runs no AppKit, so each is an
+// NSWindow made here, showing the ring the pane draws it into the same way
+// (`CocoaPaneSubwindow`, src/cocoa/panewindow.js), with its input sent back.
 import { withoutActions } from './quiet.js';
 
-export class CocoaPaneHost {
+/** One shared surface on glass: a sublayer of a window's root layer, its
+ * contents the IOSurface the pane last presented into it. */
+class PaneLayer {
   constructor(app, wnd) {
     this.app = app;
     this.wnd = wnd;
@@ -67,12 +74,14 @@ export class CocoaPaneHost {
    * error is the bug it says it is.
    */
   present(iosurfaceId) {
-    if (this.destroyed) return;
+    if (this.destroyed) return false;
     try {
       this._native.setLayerContentsIOSurface(this.layer, iosurfaceId);
     } catch (err) {
       if (!/IOSurfaceLookup/.test(err?.message ?? '')) throw err;
+      return false;
     }
+    return true;
   }
 
   destroy() {
@@ -83,3 +92,218 @@ export class CocoaPaneHost {
     );
   }
 }
+
+/**
+ * The input a window shows for the pane hands back, by the names its
+ * events go by (`CocoaApp._route`). A managed window's moves, resizes and
+ * close button go back as well (`_hostGeometry`).
+ */
+const FORWARDED = [
+  'mousedown',
+  'mouseup',
+  'mousemove',
+  'mouseout',
+  'wheel',
+  'keydown',
+  'keyup',
+  'focus',
+  'blur',
+];
+
+/** An event as data: the channel carries structured clones, and a
+ * `preventDefault` does not clone. */
+function plain(ev) {
+  const out = {};
+  for (const key in ev) {
+    const value = ev[key];
+    if (value === null || typeof value !== 'object') {
+      if (typeof value !== 'function') out[key] = value;
+    }
+  }
+  return out;
+}
+
+export class CocoaPaneHost extends PaneLayer {
+  /**
+   * `send` is the pane's channel (`<Frame>`'s session): what the windows
+   * shown here for the pane hear goes back down it.
+   */
+  constructor(app, wnd, { send } = {}) {
+    super(app, wnd);
+    this._send = send ?? null;
+    /** @type {Map<number, object>} the pane's windows, by its id for them */
+    this._windows = new Map();
+    /** @type {Map<number, () => void>} the pane's open menus, by its id */
+    this._menus = new Map();
+  }
+
+  /**
+   * A `pane-menu` message: the pane's `<Select>` asked for the platform's
+   * menu, which a process with no AppKit cannot drop (`CocoaApp.popUpMenu`).
+   * Its frame is in the window it is in — the pane's own, laid out at this
+   * layer's rect in the host's window, or one the pane made, shown here —
+   * and the answer goes back as `pane-menu-answer`.
+   */
+  popUpMenu(msg) {
+    if (this.destroyed || !msg.spec) return;
+    const entry = msg.window != null ? this._windows.get(msg.window) : null;
+    const [x, y, width, height] = msg.spec.frame;
+    const at = entry ? { x: 0, y: 0 } : (this._rect ?? { x: 0, y: 0 });
+    const cancel = this.app.popUpMenu(
+      entry ? entry.wnd : this.wnd,
+      { ...msg.spec, frame: [x + at.x, y + at.y, width, height] },
+      (id) => {
+        this._menus.delete(msg.menu);
+        this._send?.({ type: 'pane-menu-answer', menu: msg.menu, id });
+      },
+    );
+    this._menus.set(msg.menu, cancel);
+  }
+
+  /** `pane-menu-cancel`: the pane's `<Select>` went, or closed it. */
+  cancelMenu(menu) {
+    this._menus.get(menu)?.();
+  }
+
+  /**
+   * A `pane-window` message: one of the pane's other windows was made,
+   * mapped, moved, grabbed with or destroyed. `x`/`y` are the screen
+   * position the pane worked out — its anchoring ran against the origin
+   * this side sent it — so the window goes where it says.
+   */
+  paneWindow(msg) {
+    if (this.destroyed) return;
+    if (msg.op === 'create') {
+      this._create(msg);
+      return;
+    }
+    const entry = this._windows.get(msg.window);
+    if (!entry) return;
+    const { wnd } = entry;
+    switch (msg.op) {
+      case 'map':
+        // on the first frame rather than now: a window mapped before the
+        // pane has drawn it is a window of nothing, for a frame or two
+        if (entry.presented) wnd.map();
+        else entry.mapOnPresent = true;
+        break;
+      case 'unmap':
+        entry.mapOnPresent = false;
+        wnd.unmap();
+        break;
+      case 'move':
+        wnd.move(msg.x, msg.y);
+        break;
+      case 'resize':
+        // the layer follows on the present drawn at the new size
+        wnd.resize(msg.width, msg.height);
+        break;
+      case 'grab':
+        wnd.grabPointer();
+        break;
+      case 'ungrab':
+        wnd.ungrabPointer();
+        break;
+      case 'title':
+        wnd.setTitle(msg.title);
+        break;
+      case 'size-hints':
+        wnd.setSizeHints(msg.hints);
+        break;
+      case 'destroy':
+        this._drop(entry);
+        break;
+      default:
+        break;
+    }
+  }
+
+  /** A pane-present naming one of the pane's other windows. */
+  presentWindow(msg) {
+    const entry = this._windows.get(msg.window);
+    if (!entry || this.destroyed) return;
+    entry.layer.setRect({ x: 0, y: 0, width: msg.width, height: msg.height });
+    if (!entry.layer.present(msg.id)) return;
+    entry.presented = true;
+    // a transparent window's shadow is the shape of what it shows
+    entry.wnd._shadowAfterFlip?.();
+    if (entry.mapOnPresent) {
+      entry.mapOnPresent = false;
+      entry.wnd.map();
+    }
+  }
+
+  /** The cursor a tree names for one of the pane's other windows: the
+   * pointer is over the window shown here, so this side sets it. */
+  windowCursor(msg) {
+    this._windows.get(msg.window)?.wnd.setCursor(msg.cursor ?? 'default');
+  }
+
+  _create(msg) {
+    if (this._windows.has(msg.window)) return;
+    const wnd = this.app.createWindow({
+      overrideRedirect: msg.popup,
+      x: msg.x,
+      y: msg.y,
+      width: msg.width,
+      height: msg.height,
+      transparent: msg.transparent,
+      grabKeyboard: msg.grabKeyboard,
+      dragPreview: msg.dragPreview,
+      title: msg.title,
+      decorations: msg.decorations,
+      resizable: msg.resizable,
+      sizeHints: msg.sizeHints,
+    });
+    const entry = {
+      id: msg.window,
+      wnd,
+      layer: new PaneLayer(this.app, wnd),
+      presented: false,
+      mapOnPresent: false,
+    };
+    this._windows.set(msg.window, entry);
+    const forward = (name, ev) => {
+      if (this.destroyed || entry.dropped) return;
+      this._send?.({ type: 'pane-event', window: entry.id, name, ev });
+    };
+    for (const name of FORWARDED) {
+      wnd.on(name, (ev) => forward(name, plain(ev)));
+    }
+    // A popup goes where the pane puts it and no one else moves it. A
+    // managed window is the user's to move, resize and close as well, and
+    // the pane hears of each — of a resize only the user's, since the
+    // pane's own come back as AppKit's echo of the frame it was asked for.
+    if (!msg.popup) {
+      wnd.on('resize', (ev) =>
+        forward('resize', {
+          x: ev.x,
+          y: ev.y,
+          width: ev.width,
+          height: ev.height,
+          resized: Boolean(ev.resized && wnd.liveResizing),
+        }),
+      );
+      wnd.on('close', () => forward('close', {}));
+    }
+  }
+
+  _drop(entry) {
+    if (entry.dropped) return;
+    entry.dropped = true;
+    this._windows.delete(entry.id);
+    entry.wnd.ungrabPointer();
+    entry.layer.destroy();
+    entry.wnd.destroy();
+  }
+
+  /** The pane is going, and every window it had here goes with it — a pane
+   * that crashed with a menu open leaves no menu behind. */
+  destroy() {
+    if (this.destroyed) return;
+    for (const cancel of [...this._menus.values()]) cancel();
+    this._menus.clear();
+    for (const entry of [...this._windows.values()]) this._drop(entry);
+    super.destroy();
+  }
+}

package/src/cocoa/panewindow.js

@@ -14,6 +14,11 @@
 // via emit. Geometry and input arrive as channel messages (the host owns
 // layout and hit-testing — this is CPU offloading, not isolation), and what
 // goes out is pane-present, and pane-cursor for the cursor the host shows.
+//
+// Every other window the pane's tree makes — a menu, a dropdown's sheet, a
+// tooltip, a dialog — is a `CocoaPaneSubwindow`: the same ring and the same
+// presents, naming the window, and an NSWindow the host makes for it
+// (src/cocoa/panehost.js), because nothing in a pane process runs AppKit.
 import { BackendContext2D } from '../backend/context2d.js';
 
 let nextPaneId = 1;
@@ -31,13 +36,15 @@ export class CocoaPaneWindow {
     this.id = this.windowId;
     this.windowNumber = this.windowId;
     this.scale = app.scale ?? 2;
-    this.width = Math.max(
-      1,
-      Math.round((attributes.width ?? 400) * this.scale),
-    );
+    // Device pixels, as every window's attributes are (`windowAttributes`
+    // multiplies the props through once): the size the pane is born at,
+    // until the host's first pane-rect says what it is. Multiplied again
+    // here, a pane was born twice its size, and a dialog it opened in its
+    // first commit was centred over a window that was never there.
+    this.width = Math.max(1, Math.round(attributes.width ?? 400 * this.scale));
     this.height = Math.max(
       1,
-      Math.round((attributes.height ?? 300) * this.scale),
+      Math.round(attributes.height ?? 300 * this.scale),
     );
     this._listeners = new Map();
     this._surface = null;
@@ -52,27 +59,51 @@ export class CocoaPaneWindow {
     this._seq = 0;
     this._presentedAt = -Infinity;
     this._reactX11Node = null;
+    // Where the pane's corner is on the screen, in device pixels, as the
+    // host last said (`setPaneSize`): what a popup the pane anchors to one
+    // of its nodes is placed against (`windowOrigin`, src/anchor.js). The
+    // pane has no window of its own to ask, so until the host says, a menu
+    // dropped from the screen's corner.
+    this.x = 0;
+    this.y = 0;
+    this._screenOrigin = { x: 0, y: 0 };
+    // what the app's window map keys this window by, and the id the host
+    // names it by in a pane-event (`CocoaApp.attachPaneChannel`)
+    this._key = this.windowId;
     app._registerWindow(this);
   }
 
   // --- the channel-facing half --------------------------------------------
 
-  /** The host's layout answer: logical size plus the display scale. */
-  setPaneSize(width, height, scale) {
+  /**
+   * The host's layout answer: logical size plus the display scale, and
+   * where the pane is on the screen — `screen`, device pixels, absent from
+   * 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.
+   */
+  setPaneSize(width, height, scale, screen) {
     if (this.destroyed) return;
     if (scale) this.scale = scale;
     const w = Math.max(1, Math.round(width * this.scale));
     const h = Math.max(1, Math.round(height * this.scale));
-    if (w === this.width && h === this.height) return;
+    const moved =
+      screen != null && (screen.x !== this.x || screen.y !== this.y);
+    const resized = w !== this.width || h !== this.height;
+    if (!moved && !resized) return;
+    if (moved) {
+      this.x = screen.x;
+      this.y = screen.y;
+      this._screenOrigin = { x: screen.x, y: screen.y };
+    }
     this.width = w;
     this.height = h;
     this.emit('resize', {
       width: w,
       height: h,
-      x: 0,
-      y: 0,
-      moved: false,
-      resized: true,
+      x: this.x,
+      y: this.y,
+      moved,
+      resized,
     });
   }
 
@@ -103,7 +134,13 @@ export class CocoaPaneWindow {
    */
   setCursor(name) {
     if (this.destroyed) return;
-    this.app._paneSend?.({ type: 'pane-cursor', cursor: name ?? null });
+    this._post({ type: 'pane-cursor', cursor: name ?? null });
+  }
+
+  /** A message about this window, to the host. The pane's own names none:
+   * the host knows it as the pane (`CocoaPaneSubwindow` names itself). */
+  _post(msg) {
+    this.app._paneSend?.(msg);
   }
 
   requestAnimationFrame(cb) {
@@ -264,7 +301,7 @@ export class CocoaPaneWindow {
     const shown = this._ring[this._drawIndex];
     this._native.surfaceUnlock(shown.handle);
     this._flushDamage = null;
-    this.app._paneSend?.({
+    this._post({
       type: 'pane-present',
       seq: ++this._seq,
       id: shown.iosurfaceId,
@@ -304,3 +341,156 @@ export class CocoaPaneWindow {
     this._releaseRing();
   }
 }
+
+/**
+ * Any other window a pane's tree makes: a `<popup>` — a menu, a dropdown's
+ * sheet, a tooltip, the edit menu — or a managed one, a dialog (#824).
+ *
+ * A pane process runs no AppKit (`CocoaApp.start`): no NSApplication, no
+ * event pump. An NSWindow made here exists and is never shown, so a
+ * `<Select>` in a pane took the press, opened, and showed nothing. This
+ * window paints into a shared ring exactly as the pane does, and the host
+ * makes the NSWindow and shows the ring in it (`CocoaPaneHost`,
+ * src/cocoa/panehost.js) — the split the pane already has: the pane draws,
+ * the host owns glass and input.
+ *
+ * Its place is the pane's to decide and the host's to take as given: `x`
+ * and `y` are the screen position the pane's own anchoring worked out,
+ * against the origin the host sends with every pane-rect. What goes out is
+ * the window's life as `pane-window` messages and its frames as
+ * `pane-present`s naming it; what comes back is the input on the host's
+ * window, as `pane-event`s naming it, and for a managed window the moves
+ * and the resizes the user made and the close button.
+ */
+export class CocoaPaneSubwindow extends CocoaPaneWindow {
+  constructor(app, attributes = {}) {
+    super(app, attributes);
+    this.attributes = attributes;
+    this._popup = attributes.overrideRedirect === true;
+    this.mapped = false;
+    // device pixels, as every window's attributes are — unlike the pane's
+    // own, whose size is the host's to say
+    const size = this.snapSize(attributes.width ?? 1, attributes.height ?? 1);
+    this.width = size.width;
+    this.height = size.height;
+    this.x = Math.round(attributes.x ?? 0);
+    this.y = Math.round(attributes.y ?? 0);
+    this._screenOrigin = { x: this.x, y: this.y };
+    this._send({
+      op: 'create',
+      x: this.x,
+      y: this.y,
+      width: this.width,
+      height: this.height,
+      popup: this._popup,
+      // an ARGB visual is a transparent window here, as in `CocoaWindow`
+      transparent:
+        attributes.visual !== undefined || Boolean(attributes.transparent),
+      grabKeyboard: attributes.grabKeyboard === true,
+      dragPreview: Boolean(attributes.dragPreview),
+      title: attributes.title ?? '',
+      decorations: attributes.decorations,
+      resizable: attributes.resizable,
+      sizeHints: attributes.sizeHints,
+    });
+  }
+
+  /** Named, and held until the host is listening (`CocoaApp._postWindow`). */
+  _post(msg) {
+    this.app._postWindow({ ...msg, window: this.windowId });
+  }
+
+  _send(msg) {
+    if (this.destroyed) return;
+    this._post({ type: 'pane-window', ...msg });
+  }
+
+  /** `CocoaWindow`'s rule, so the size this window records is the size the
+   * host's NSWindow will take: whole points, rounded up. */
+  snapSize(width, height) {
+    const s = this.scale;
+    const up = (v) =>
+      Math.max(1, Math.ceil(Math.max(1, Math.round(v)) / s) * s);
+    return { width: up(width), height: up(height) };
+  }
+
+  map() {
+    this.mapped = true;
+    this._send({ op: 'map' });
+  }
+
+  unmap() {
+    this.mapped = false;
+    this._send({ op: 'unmap' });
+  }
+
+  move(x, y) {
+    this.x = Math.round(x);
+    this.y = Math.round(y);
+    this._screenOrigin = { x: this.x, y: this.y };
+    this._send({ op: 'move', x: this.x, y: this.y });
+  }
+
+  resize(width, height) {
+    const size = this.snapSize(width, height);
+    this.width = size.width;
+    this.height = size.height;
+    this._send({ op: 'resize', width: this.width, height: this.height });
+  }
+
+  setTitle(title) {
+    this._send({ op: 'title', title: String(title ?? '') });
+  }
+
+  setSizeHints(hints = {}) {
+    this._send({ op: 'size-hints', hints: { ...hints } });
+  }
+
+  /** The grab is the host's: a press anywhere in its windows comes here,
+   * outside this window, which is the dismissal (`CocoaApp._grabTarget`). */
+  grabPointer(options, cb) {
+    this._send({ op: 'grab' });
+    cb?.(null, 0);
+  }
+
+  ungrabPointer() {
+    this._send({ op: 'ungrab' });
+  }
+
+  /**
+   * Where the host's window went for a reason of its own — the user moved a
+   * dialog, or resized it — which a `resize` here says as a window's own
+   * move or resize does. A size comes only from the user (`resized`): the
+   * pane's own resizes come back as the host's echo, and one taken as news
+   * would read as the user taking an `'auto'` window over.
+   */
+  _hostGeometry(ev) {
+    if (this.destroyed) return;
+    const moved = ev.x !== this.x || ev.y !== this.y;
+    const resized =
+      Boolean(ev.resized) &&
+      (ev.width !== this.width || ev.height !== this.height);
+    if (!moved && !resized) return;
+    this.x = ev.x;
+    this.y = ev.y;
+    this._screenOrigin = { x: ev.x, y: ev.y };
+    if (resized) {
+      this.width = ev.width;
+      this.height = ev.height;
+    }
+    this.emit('resize', {
+      width: this.width,
+      height: this.height,
+      x: this.x,
+      y: this.y,
+      moved,
+      resized,
+    });
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this._send({ op: 'destroy' });
+    super.destroy();
+  }
+}

package/src/cocoa/promotion.js

@@ -591,8 +591,16 @@ export class CocoaPromotion {
    * node's reach, the parent's clip, if it has one, must hold the whole of
    * it, and the parent must not fade: its group is drawn on the bitmap or on
    * its own layer, and either way a layer of the node's would be outside it.
+   *
+   * With `cut`, the reach is an element's part (src/cocoa/sprites.js),
+   * whose layer can be cut to a rectangle: a clipping ancestor with square
+   * corners narrows `cut.clip` to its padding box — its border is drawn
+   * over what it holds anyway — instead of having to hold the part whole,
+   * and every test from there up is asked of what shows through the clip.
+   * `cut.bounds` comes back as that. A clip that leaves nothing showing is
+   * a refusal.
    */
-  _clear(node, bounds = node._subtreeBounds()) {
+  _clear(node, bounds = node._subtreeBounds(), cut = null) {
     // the exact reach, not `paintBounds()`: that one carries the damage
     // model's pixel of slop, and a section laid out flush under a card
     // would read as reaching into it. An element's part is asked about at
@@ -600,6 +608,17 @@ export class CocoaPromotion {
     for (let n = node; !n.isWindow; n = n.parent) {
       const parent = n.parent;
       if (!parent) return false;
+      if (
+        cut &&
+        !parent.isWindow &&
+        parent.clipsChildren?.() &&
+        !(parent.style?.borderRadius > 0)
+      ) {
+        const inner = insetRect(parent.abs, borderReach(parent));
+        cut.clip = cut.clip ? intersectRects(cut.clip, inner) : inner;
+        bounds = cut.clip && intersectRects(bounds, cut.clip);
+        if (!bounds) return false;
+      }
       const order = parent.paintOrder();
       for (let j = order.indexOf(n) + 1; j < order.length; j++) {
         if (this._reaches(order[j], bounds)) return false;
@@ -636,6 +655,7 @@ export class CocoaPromotion {
         }
       }
     }
+    if (cut) cut.bounds = bounds;
     return true;
   }
 

package/src/cocoa/sprites.js

@@ -25,6 +25,7 @@
 // element.
 
 import { RASTER_PAD, RasterState } from './presenter.js';
+import { intersectRects } from '../nodes/rects.js';
 import { DEV } from '../nodes/util.js';
 
 // Past this many device pixels on a side a part is drawn by its element: a
@@ -109,6 +110,7 @@ function isSprite(sprite) {
   if (sprite == null || typeof sprite.key !== 'string') return false;
   if (!isRect(sprite.rect) || typeof sprite.paint !== 'function') return false;
   if (sprite.reach !== undefined && !isRect(sprite.reach)) return false;
+  if (sprite.clip !== undefined && !isRect(sprite.clip)) return false;
   if (sprite.opacity !== undefined && !finite(sprite.opacity)) return false;
   if (sprite.transform !== undefined && !isMatrix(sprite.transform)) {
     return false;
@@ -304,18 +306,30 @@ export class SpriteLayers {
         if (now.has(sprite.key)) continue;
         const raster = rasterRectOf(sprite);
         if (raster.width > MAX_SIDE || raster.height > MAX_SIDE) continue;
+        // what shows of everywhere it can be: inside its own clip, and the
+        // clips of its element's ancestors, which cut its layer (`_clear`)
+        const cut = { clip: sprite.clip ?? null, bounds: null };
         const extent = extentOf(sprite);
-        if (!this.promotion._clear(host, extent)) continue;
+        const bounds = cut.clip ? intersectRects(extent, cut.clip) : extent;
+        if (!bounds || !this.promotion._clear(host, bounds, cut)) continue;
+        const shown = cut.bounds;
         let state = was?.get(sprite.key);
+        // a clip that comes or goes is a layer in a box or out of one: lifted
+        // again, rather than a running layer moved between parents
+        if (state && Boolean(state.clip) !== Boolean(cut.clip)) {
+          this._drop(state, root);
+          state = null;
+        }
         const lifting = !state;
-        if (lifting) state = this._lift(host, sprite.key);
+        if (lifting) state = this._lift(host, sprite.key, cut.clip !== null);
         state.sprite = sprite;
+        state.clip = cut.clip;
         state.order = [...place, AFTER_CHILDREN, index];
-        // the bitmap under where it can be repaints without it, from this
+        // the bitmap under where it shows repaints without it, from this
         // frame on; where it went since, it is the element's own claims
         // that move the hole
-        if (lifting) this.promotion._claim(root, extent);
-        state.extent = extent;
+        if (lifting) this.promotion._claim(root, shown);
+        state.extent = shown;
         now.set(sprite.key, state);
       }
       if (was) {
@@ -356,13 +370,25 @@ export class SpriteLayers {
     }
   }
 
-  _lift(host, key) {
+  _lift(host, key, clipped) {
     const layer = this.native.createLayer();
-    this.native.addSublayer(this.promotion.rootVisual.layer, layer);
+    // a part cut to a clip is in a box of the clip's size that masks to it,
+    // and the box is what stands among the layers above the bitmap
+    let box = null;
+    if (clipped) {
+      box = this.native.createLayer();
+      this.native.addSublayer(this.promotion.rootVisual.layer, box);
+      this.native.addSublayer(box, layer);
+    } else {
+      this.native.addSublayer(this.promotion.rootVisual.layer, layer);
+    }
     return {
       host,
       key,
       layer,
+      box,
+      boxProps: {},
+      clip: null, // device pixels, window coordinates
       raster: new RasterState(),
       painted: UNPAINTED,
       rect: null, // the raster's rect, device pixels, window coordinates
@@ -383,7 +409,7 @@ export class SpriteLayers {
    *  forgotten, and the bitmap under where it could be repaints with the
    *  element drawing it again. */
   _drop(state, root) {
-    this.native.removeFromSuperlayer(state.layer);
+    this.native.removeFromSuperlayer(state.box ?? state.layer);
     state.raster.release(this.native);
     for (const run of state.runs.values()) this._ends().delete(run.caId);
     state.runs.clear();
@@ -415,14 +441,31 @@ export class SpriteLayers {
     state.rect = rect;
     const origin = originOf(sprite);
     const m = sprite.transform ?? IDENTITY;
+    // in its box, where it is cut to a clip: placed from the clip's corner,
+    // and the box at the part's place among the layers
+    const clip = state.clip;
+    if (state.box) {
+      const frame = [clip.x / s, clip.y / s, clip.width / s, clip.height / s];
+      const was = state.boxProps;
+      if (!sameMatrix(was.frame, frame) || was.zPosition !== z) {
+        this.native.setLayerProps(state.box, {
+          frame,
+          masksToBounds: true,
+          zPosition: z,
+        });
+        state.boxProps = { frame, zPosition: z };
+      }
+    }
+    const ox = state.box ? clip.x : 0;
+    const oy = state.box ? clip.y : 0;
     const next = {
       bounds: [0, 0, rect.width / s, rect.height / s],
       anchorPoint: [
         (origin.x - rect.x) / rect.width,
         (origin.y - rect.y) / rect.height,
       ],
-      position: [origin.x / s, origin.y / s],
-      zPosition: z,
+      position: [(origin.x - ox) / s, (origin.y - oy) / s],
+      zPosition: state.box ? 0 : z,
       opacity: Math.min(1, Math.max(0, sprite.opacity ?? 1)),
       matrix: m,
     };
@@ -552,7 +595,7 @@ export class SpriteLayers {
   destroy() {
     for (const lifted of this.hosts.values()) {
       for (const state of lifted.values()) {
-        this.native.removeFromSuperlayer(state.layer);
+        this.native.removeFromSuperlayer(state.box ?? state.layer);
         state.raster.release(this.native);
         for (const run of state.runs.values()) this._ends().delete(run.caId);
       }

package/src/components/Select.js

@@ -143,6 +143,33 @@ const TRIGGER_PAD_LEFT = 10;
 // (`nodes/scrollbars.js`, SCROLLBAR_WIDTH), so a menu that scrolls reserves the room
 const SCROLLBAR_WIDTH = 6;
 
+// The family a caption's style names, for the platform's menu: the first of
+// a CSS list, unquoted, and nothing for a generic one, which is the menu
+// font's own to answer.
+const GENERIC_FAMILIES = new Set([
+  'sans-serif',
+  'serif',
+  'monospace',
+  'cursive',
+  'fantasy',
+  'system-ui',
+  'ui-sans-serif',
+  'ui-serif',
+  'ui-monospace',
+  '-apple-system',
+  'blinkmacsystemfont',
+]);
+function menuFamily(family) {
+  if (typeof family !== 'string') return undefined;
+  const first = family
+    .split(',')[0]
+    .trim()
+    .replace(/^["']|["']$/g, '');
+  return first && !GENERIC_FAMILIES.has(first.toLowerCase())
+    ? first
+    : undefined;
+}
+
 function normalizeOption(option) {
   return typeof option === 'object' && option !== null
     ? option
@@ -291,6 +318,17 @@ function Option({
  * caption's `fontSize` is read back: the chevron is as tall as the capitals
  * beside it. Any slot also chooses the drawn trigger over the platform's
  * popup bezel, whose pixels no style reaches.
+ *
+ * `nativeMenu` is the menu's half of `native`: where the backend drops a
+ * control's menu as the platform's own (`app.nativePopUpMenus`, macOS), the
+ * list is that menu — the chosen row over the trigger, the platform's
+ * tracking, type-select and VoiceOver — rather than a `<popup>` drawn to
+ * look like it. It follows the trigger by default, so a select under the
+ * native bezel gets the native menu and a drawn one keeps the drawn menu;
+ * `true` asks for the platform's menu under a drawn trigger too, which is
+ * 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.
  */
 export function Select({
   value,
@@ -299,6 +337,7 @@ export function Select({
   name,
   placeholder = 'Select…',
   native,
+  nativeMenu,
   style,
   labelStyle,
   chevronStyle,
@@ -308,11 +347,20 @@ export function Select({
   const app = useAppOrNull();
   const styled = Boolean(labelStyle || chevronStyle);
   const nativeControls = useNativeControls(styled ? false : native);
+  // the platform's own menu, where there is one and this select wants it
+  const platformMenu =
+    (nativeMenu ?? nativeControls) && Boolean(app?.nativePopUpMenus);
   // The size the caption is set in, where its slot names one: the chevron is
   // measured against those capitals, and an `<Icon>`'s size does not inherit.
   const ownSize = flattenStyle(labelStyle).fontSize;
   const captionSize = typeof ownSize === 'number' ? ownSize : theme.fontSize;
   const [open, setOpen] = useState(false);
+  // The platform's menu, while it is down: its cancel function, and whether
+  // it is open, for the trigger's open look and `aria-expanded`.
+  const platformRef = useRef(null);
+  const [platformOpen, setPlatformOpen] = useState(false);
+  // a menu is down, whichever one: the trigger's open look follows it
+  const expanded = open || platformOpen;
   const [anchor, setAnchor] = useState(null);
   const [focused, setFocused] = useState(false);
   const [activeIndex, setActiveIndex] = useState(-1);
@@ -387,8 +435,48 @@ export function Select({
     };
   };
 
-  const close = () => setOpen(false);
+  const close = () => {
+    setOpen(false);
+    platformRef.current?.();
+  };
+  // The platform's menu, dropped from the trigger: the same options, the
+  // current one placed over it. Its answer is a pick like a row's.
+  const openPlatformMenu = () => {
+    const node = triggerRef.current;
+    const wnd = node?.root?.window;
+    if (!node || !wnd || platformRef.current) return;
+    const chosen = normalized.findIndex((o) => o.value === value);
+    const family = menuFamily(flattenStyle(labelStyle).fontFamily);
+    setPlatformOpen(true);
+    platformRef.current = app.popUpMenu(
+      wnd,
+      {
+        items: normalized.map((o, i) => ({
+          id: i + 1,
+          title: String(o.label),
+        })),
+        frame: [node.abs.x, node.abs.y, node.abs.width, node.abs.height],
+        ...(chosen >= 0 && { selected: chosen + 1 }),
+        // under the bezel the menu is the bezel's, at the menu font's size
+        ...(!nativeControls && { fontSize: captionSize }),
+        ...(!nativeControls && family && { fontFamily: family }),
+        // the theme's, as the bezel's appearance is
+        appearance: theme.scheme === 'dark' ? 'dark' : 'light',
+        rtl: node.direction === 'rtl',
+      },
+      (id) => {
+        platformRef.current = null;
+        setPlatformOpen(false);
+        const option = id != null ? normalized[id - 1] : null;
+        if (option && option.value !== value) emit(option.value);
+      },
+    );
+  };
   const openMenu = () => {
+    if (platformMenu) {
+      openPlatformMenu();
+      return;
+    }
     const node = triggerRef.current;
     if (!node) return;
     const rect = measureAnchor(menuAnchorOptions());
@@ -398,7 +486,9 @@ export function Select({
     setActiveIndex(selected >= 0 ? selected : 0);
     setOpen(true);
   };
-  const toggle = () => (open ? close() : openMenu());
+  const toggle = () => (expanded ? close() : openMenu());
+  // a menu still down when the select goes is taken with it
+  useEffect(() => () => platformRef.current?.(), []);
 
   // keeps the menu under the trigger for as long as it is open: a scrolled
   // ancestor, the trigger's own layout moving it (a neighbouring field
@@ -491,7 +581,7 @@ export function Select({
     {
       theme,
       role: 'combobox',
-      'aria-expanded': open,
+      'aria-expanded': expanded,
       'aria-haspopup': 'listbox',
       ref: triggerRef,
       focusable: true,
@@ -546,7 +636,8 @@ export function Select({
               paddingRight: 10,
               borderWidth: theme.borderWidth,
               borderRadius: theme.radius,
-              borderColor: focused || open ? theme.borderFocus : theme.border,
+              borderColor:
+                focused || expanded ? theme.borderFocus : theme.border,
               backgroundColor: theme.surface,
             },
         // Hover and press belong to the trigger while it is *shut*: they say
@@ -560,7 +651,7 @@ export function Select({
         // not overwrite. The only way for open to win is to not be competing.
         // (In native mode the wash overlay below answers the press instead.)
         !nativeControls &&
-          !open && {
+          !expanded && {
             ':hover': { backgroundColor: theme.surfaceHover },
             ':active': { backgroundColor: theme.surfaceActive },
           },
@@ -576,7 +667,7 @@ export function Select({
     nativeControls &&
       h(Bezel, {
         kind: 'popup',
-        pressed: open,
+        pressed: expanded,
         enabled: true,
         style: ABS_FILL,
       }),
@@ -605,7 +696,7 @@ export function Select({
           style: [
             ABS_FILL,
             { borderRadius: 6 },
-            !open && { ':active': { backgroundColor: pressWash(theme) } },
+            !expanded && { ':active': { backgroundColor: pressWash(theme) } },
           ],
         })
       : h(Icon, {

package/src/frame/index.js

@@ -529,7 +529,9 @@ function PaneHostView({
     }
     let host;
     try {
-      host = app.createPaneHost(wnd);
+      // `send` is for the windows the pane makes besides its own, which a
+      // backend whose pane process cannot show one shows here (Cocoa's)
+      host = app.createPaneHost(wnd, { send: (msg) => s.trySend?.(msg) });
     } catch (err) {
       embedErrorRef.current?.(err);
       return undefined;
@@ -539,17 +541,44 @@ function PaneHostView({
     // The pane's size is this box's laid-out size, told to the pane whenever
     // it changes — the same absolutize hook a <foreign> child window uses
     // (src/foreignnodes.js), because onViewport fires only for scrollers.
-    let sentSize = null;
+    //
+    // And where the box is on the screen, in device pixels (`screen`): the
+    // pane has no window of its own to ask, and a popup it anchors to one of
+    // its nodes is placed against it (`windowOrigin`, src/anchor.js) — a
+    // dropdown in a pane opened from the screen's corner without it. It
+    // moves when the box does and when the window does, so it is sent on
+    // layout, on a scroll that shifts the box, and on every anchor change
+    // of the window, which a move of the window is.
+    let sent = null;
     const syncSize = () => {
       host.setRect(node.abs);
       const sc = node.scale ?? 1;
       const width = Math.max(1, Math.round(node.abs.width / sc));
       const height = Math.max(1, Math.round(node.abs.height / sc));
-      if (sentSize && sentSize.width === width && sentSize.height === height) {
+      const origin = node.root?.window?._screenOrigin;
+      const screen = origin
+        ? {
+            x: Math.round(origin.x + node.abs.x),
+            y: Math.round(origin.y + node.abs.y),
+          }
+        : null;
+      if (
+        sent &&
+        sent.width === width &&
+        sent.height === height &&
+        sent.screen?.x === screen?.x &&
+        sent.screen?.y === screen?.y
+      ) {
         return;
       }
-      sentSize = { width, height };
-      s.trySend?.({ type: 'pane-rect', width, height, scale: sc });
+      sent = { width, height, screen };
+      s.trySend?.({
+        type: 'pane-rect',
+        width,
+        height,
+        scale: sc,
+        ...(screen && { screen }),
+      });
     };
     const origAbsolutize = node.absolutize.bind(node);
     node.absolutize = (ox, oy) => {
@@ -560,13 +589,35 @@ function PaneHostView({
     if (origShift) {
       node._shiftAbs = (dx, dy) => {
         origShift(dx, dy);
-        host.setRect(node.abs);
+        syncSize();
       };
     }
+    const offAnchor = node.root?.onAnchorChange?.(syncSize);
     if (node.abs?.width) syncSize();
 
+    // The window's focus, which the pane has no window to hear: a menu it
+    // keeps open on the strength of the window having it closes when the
+    // user goes to another application (`useDismissOnWindowBlur`).
+    const offFocus = node.root?.onWindowFocusChange?.((focused) =>
+      s.trySend?.({
+        type: 'pane-event',
+        name: focused ? 'focus' : 'blur',
+        ev: { buttons: 0, time: Date.now() },
+      }),
+    );
+
     const off = s.transport.onMessage((msg) => {
-      if (msg?.type === 'pane-present') {
+      if (msg?.type === 'pane-window') {
+        host.paneWindow?.(msg);
+      } else if (msg?.type === 'pane-menu') {
+        host.popUpMenu?.(msg);
+      } else if (msg?.type === 'pane-menu-cancel') {
+        host.cancelMenu?.(msg.menu);
+      } else if (msg?.type === 'pane-present' && msg.window != null) {
+        host.presentWindow?.(msg);
+      } else if (msg?.type === 'pane-cursor' && msg.window != null) {
+        host.windowCursor?.(msg);
+      } else if (msg?.type === 'pane-present') {
         host.setRect(node.abs);
         host.present(msg.id);
       } else if (msg?.type === 'pane-cursor') {
@@ -581,6 +632,8 @@ function PaneHostView({
     });
     return () => {
       off();
+      offAnchor?.();
+      offFocus?.();
       node.defaultCursor = undefined;
       node.root?.events?.refreshCursor();
       node.absolutize = origAbsolutize;

package/src/node.d.ts

@@ -284,6 +284,11 @@ export interface Sprite {
   rect: Rect;
   /** What it draws, untransformed, when that is more than `rect`. */
   reach?: Rect;
+  /** Where it shows, when the element clips it: device pixels, window
+   * coordinates. Its layer is cut to the rect, and so it is to the clip of
+   * every ancestor with square corners (a rounded one has to hold all of
+   * it). */
+  clip?: Rect;
   /** Draws the part where it is in the window, as `paint` would, but at
    * opacity 1 and untransformed. */
   paint(ctx: Context2D): void;

package/src/nodes/window/window.js

@@ -550,12 +550,22 @@ export class WindowNode extends Scrollable(Node) {
    * relative to the *frame*, not the root. A popup anchored with them lands
    * near the corner of the screen instead of under its trigger. The server
    * will translate for us, and its answer is right whatever the WM did.
+   *
+   * A backend with no server to ask keeps the origin on its window object
+   * itself, current as of the event that moved it — Cocoa's
+   * `_nativeResized`, a frame pane's `setPaneSize`. There is no question to
+   * ask there, and what is left is what the answer would have done: tell
+   * whatever is anchored to this window that it moved. Without it a popup
+   * stayed where the window had been, and a frame pane told its new place
+   * on the screen dropped its next menu from the old one.
    */
   _refreshScreenOrigin() {
     const wnd = this.window;
+    if (!wnd) return;
     const X = this.app?.X;
     const root = X?.display?.screen?.[0]?.root;
-    if (!wnd || root == null || typeof X.TranslateCoordinates !== 'function') {
+    if (root == null || typeof X.TranslateCoordinates !== 'function') {
+      this._notifyAnchorChange();
       return;
     }
     X.TranslateCoordinates(wnd.id, root, 0, 0, (err, res) => {

package/src/types/components.d.ts

@@ -521,6 +521,16 @@ export interface SelectProps<T = unknown>
   /** The chevron's style, over `textMuted` at the caption's cap height.
    *  `display: 'none'` leaves it out. */
   chevronStyle?: StyleProp;
+  /**
+   * The menu's half of `native`: where the backend drops a control's menu
+   * as the platform's own (macOS, with `@windowkit/appkit` 0.20 or later),
+   * the list is that menu rather than a drawn one. Follows the trigger by
+   * default — the native bezel's select gets the native menu, a drawn one
+   * the drawn menu. `true` asks for the platform's menu under a drawn
+   * trigger too, set at the caption's size; `false` keeps the drawn menu.
+   * Ignored where the backend has no such menu.
+   */
+  nativeMenu?: boolean;
 }
 export function Select<T = unknown>(props: SelectProps<T>): ReactNode;