react-x11 2.16.0 → 2.17.0

package/src/capabilities.js

@@ -79,6 +79,21 @@ function soleApp() {
   return showing.length === 1 ? showing[0] : null;
 }
 
+/**
+ * The mechanism a backend says it built one rung on, or null.
+ *
+ * Backends install the *same method names* for the same rung on purpose --
+ * `createStatusItem` is how `useTray` stays one hook -- so a method name
+ * cannot tell two mechanisms apart, and a probe that tried reported
+ * Shell_NotifyIcon as `cocoa`. A backend with more than one mechanism to
+ * distinguish declares them (`app.shellMechanisms`); one with nothing to
+ * disambiguate says nothing and the method checks below still answer.
+ */
+function shellMechanism(target, rung) {
+  const declared = target?.shellMechanisms;
+  return typeof declared?.[rung] === 'string' ? declared[rung] : null;
+}
+
 // ---------------------------------------------------------------------------
 // notifications
 // ---------------------------------------------------------------------------
@@ -154,6 +169,27 @@ async function probeNotifications({ app } = {}) {
     });
   }
 
+  if (backend === 'win32') {
+    // A Shell_NotifyIcon balloon: text with a severity, shown by the tray
+    // icon and kept by the Action Center afterwards. Everything richer is a
+    // toast, which is WinRT and a different mechanism entirely.
+    return frozen('win32', {
+      actions: false,
+      events: false, // NIN_BALLOONUSERCLICK is not routed
+      update: false,
+      close: false,
+      body: true,
+      bodyMarkup: false,
+      bodyImage: false,
+      // The balloon shows the severity's own glyph. NIIF_USER would put the
+      // caller's icon there and is not wired up, so an icon cannot be chosen.
+      icon: false,
+      sound: true, // the shell plays one; NIIF_NOSOUND is not set
+      persistence: true, // it lands in the Action Center
+      urgency: true, // low/normal/critical -> NIIF_NONE/INFO/ERROR
+    });
+  }
+
   // `osascript` and `notify-send`: one way, and that is the whole of it.
   // `notify-send -p` prints an id on newer libnotify, which is why `update`
   // is not flatly false there — see notifications.js.
@@ -178,6 +214,33 @@ async function probeNotifications({ app } = {}) {
 
 /** The tray on an app that has one of its own, which needs nothing asked. */
 function trayNow(target) {
+  // The mechanism is *declared* by the backend, not guessed from a method
+  // name, because two backends deliberately install the same names -- that
+  // sharing is what lets `useTray` be one hook -- and a probe that read
+  // `createStatusItem` as "this is AppKit" reported Shell_NotifyIcon as
+  // `cocoa`, with SF Symbols and click modifiers it does not have.
+  if (shellMechanism(target, 'tray') === 'shellnotifyicon') {
+    return frozen('shellnotifyicon', {
+      menu: true,
+      // No name vocabulary: the shell has no icon theme to look a name up
+      // in, so an icon here is always pixels or a file.
+      iconName: false,
+      iconBytes: true,
+      attention: false,
+      overlay: false,
+      tooltip: true,
+      // An NSStatusItem can show a label beside its icon; a notify icon is
+      // an icon. `title` is accepted and used as the tooltip, which is a
+      // fallback rather than the feature.
+      title: false,
+      click: true,
+      clickPosition: true,
+      clickRect: false,
+      clickModifiers: false,
+      // WM_MOUSEWHEEL is not delivered to a notify icon.
+      scroll: false,
+    });
+  }
   if (typeof target?.createStatusItem === 'function') {
     return frozen('cocoa', {
       menu: true,
@@ -234,15 +297,45 @@ async function probeTray({ app } = {}) {
 
 /** The Dock tile on an app that has one, which needs nothing asked. */
 function launcherNow(target) {
+  // Declared, not guessed -- see `trayNow`. This backend installs
+  // `setDockBadge` too, so the cocoa branch below used to answer for it and
+  // say `progress: false` with a working taskbar progress bar right there.
+  if (shellMechanism(target, 'launcher') === 'taskbar') {
+    return frozen('taskbar', {
+      badge: true,
+      // Drawn into the overlay icon, so it is text rather than a count --
+      // but a 16x16 overlay holds about three glyphs and longer labels come
+      // out as `99+`.
+      badgeText: true,
+      progress: true, // ITaskbarList3::SetProgressValue
+      urgent: true, // FlashWindowEx
+      // The taskbar button's menu is the jump list, whose entries start a
+      // *new* process; nothing on it can call back into this one. That is a
+      // different feature from the Dock menu, and `tasks` is its name --
+      // reporting `menu: true` here would promise a callback that never
+      // comes.
+      menu: false,
+      needsDesktopFile: false,
+      tasks: typeof target.jumpList === 'function',
+      thumbnailToolbar: typeof target.thumbnailToolbar === 'function',
+      recentDocuments: typeof target.noteRecentDocument === 'function',
+    });
+  }
   if (typeof target?.setDockBadge === 'function') {
     return frozen('cocoa', {
       badge: true,
       badgeText: true, // the tile takes any label
       progress: false, // NSDockTile has no progress bar
       urgent: true, // requestUserAttention, via window states
-      menu: typeof target.setDockMenu === 'function',
+      menu: typeof target.setLauncherMenu === 'function',
       // The Dock always shows the app; nothing has to be installed for it.
       needsDesktopFile: false,
+      // The Dock has no static-task menu and no hover toolbar. macOS does
+      // keep a Recent list (`noteNewRecentDocumentURL:`), but this backend
+      // has nothing wired to it, and the map says what the backend can do.
+      tasks: false,
+      thumbnailToolbar: false,
+      recentDocuments: typeof target.noteRecentDocument === 'function',
     });
   }
   return null;
@@ -283,6 +376,11 @@ async function probeLauncher({ app } = {}) {
     urgent: true,
     menu: true, // the quicklist
     needsDesktopFile: true,
+    // The quicklist is the menu; `Actions=` in the .desktop file are the
+    // closest thing to static tasks and are not driven from here.
+    tasks: false,
+    thumbnailToolbar: false,
+    recentDocuments: false,
   });
 }
 

package/src/cocoa/app.js

@@ -22,7 +22,7 @@ import { deliverActivate, deliverOpen } from '../application.js';
 import { flushPendingFrames } from '../frames.js';
 import { flushSyncWork } from '../priority.js';
 import { setCompositingForTests } from '../compositing.js';
-import { setScreensForTests } from '../screens.js';
+import { setScreenPolling, setScreensForTests } from '../screens.js';
 import { setScaleForTests } from '../scale.js';
 import { BezelStore } from './bezels.js';
 import { CocoaGLArea, cocoaGLConfig, resolveCocoaGLRuntime } from './glarea.js';
@@ -38,7 +38,7 @@ import { CocoaPaneWindow } from './panewindow.js';
 import { CocoaColorSampler } from './screencolor.js';
 import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
-import { releaseImageUpload } from './context2d.js';
+import { releaseImageUpload } from '../backend/context2d.js';
 import { CocoaSurface } from './surface.js';
 import { CocoaSymbols } from './symbols.js';
 import { CocoaWindow } from './window.js';
@@ -70,6 +70,23 @@ const FRAME_SLACK_MS = 1;
 // to 100, docs/windows.md §"Resize"). `createRoot({ cocoa: { resizeWait } })`
 // sets it; 0 is no handshake at all.
 const RESIZE_WAIT_MS = 50;
+// How often the screen layout is re-read while something is watching it, in
+// ms. There is no event to wait for — the bridge keeps its `NSScreen` copy
+// current on macOS's notification and emits nothing (#617) — so
+// `useScreens()`'s promise to re-render when a monitor is plugged in is
+// kept by asking. 500 is half a second behind a replug, which is under the
+// time it takes to look at the screen, against one `listScreens()` read a
+// second (a lock and a few doubles on a worker, an `NSScreen.screens` walk
+// on the main thread). Only while a component is subscribed:
+// `createRoot({ cocoa: { screenPoll } })` sets it, 0 turns it off, and
+// nothing polls in an app that never calls `useScreens()`.
+const SCREEN_POLL_MS = 500;
+// The floor under a re-read driven by something that is *not* a clock: a
+// window reporting where it is, which a drag reports every frame and a
+// display change reports once. A second is far too long to matter to a
+// person and short enough that a rearrangement is noticed by the time they
+// have finished moving the window (`_recheckScreens`).
+const SCREEN_RECHECK_MS = 1000;
 
 export class CocoaApp {
   constructor(native, options = {}) {
@@ -157,6 +174,26 @@ export class CocoaApp {
     const screens = native.listScreens();
     this.scale = screens[0]?.scale ?? 1;
     this._screens = screens;
+    // …and how the layout stays current, because nothing pushes it: the
+    // bridge republishes its copy on macOS's own notification but emits no
+    // event, so this side asks — before a placement reads the layout, when
+    // a window reports a move, and on a clock while `useScreens()` has a
+    // subscriber (`refreshScreens`, #617). `_screensAt` is when the last
+    // read happened, which is what throttles the ones that are not clocks.
+    this._screensAt = performance.now();
+    this._screenTimer = null;
+    const screenPoll = options.cocoa?.screenPoll ?? SCREEN_POLL_MS;
+    if (!(screenPoll >= 0) || !Number.isFinite(screenPoll)) {
+      throw new TypeError(
+        'react-x11: cocoa.screenPoll is a number of milliseconds, 0 for ' +
+          `none — got ${screenPoll}.`,
+      );
+    }
+    this._screenPoll = screenPoll;
+    setScreenPolling(this, {
+      revalidate: () => this.refreshScreens(),
+      watched: (on) => this._pollScreens(on),
+    });
 
     // The name the Dock, ⌘-Tab and the menu bar print. An unbundled
     // process is registered with LaunchServices under its executable —
@@ -167,7 +204,7 @@ export class CocoaApp {
       native.setAppName(String(appName));
     }
 
-    // The Dock menu (src/cocoa/dock.js), installed by `useDockMenu`.
+    // The Dock menu (src/cocoa/dock.js), installed by `useLauncherMenu`.
     this._dockMenu = new CocoaDockMenu(this);
     // The tray items (src/cocoa/statusitem.js), by the bridge's handle —
     // which is what a click event names them by.
@@ -504,6 +541,102 @@ export class CocoaApp {
     this._windows.set(wnd._key, wnd);
   }
 
+  /**
+   * Re-read the screen layout and publish it if the desk has changed — the
+   * answer to a monitor plugged in, unplugged, rearranged, woken or made
+   * primary (#617). Returns whether anything moved.
+   *
+   * **`listScreens()` is always current; this side's copy was not.** The
+   * bridge republishes its `NSScreen` snapshot on
+   * `NSApplicationDidChangeScreenParametersNotification` and answers a
+   * pump-mode call from AppKit live — what was read once and kept forever
+   * is `_screens`, taken in the constructor. So the whole fix is to ask
+   * again, and the read is cheap enough to ask on demand: before a
+   * placement clamps a popup to a monitor (`availableArea` through
+   * `setScreenPolling`), when a window reports a move (`_recheckScreens`),
+   * and on a clock while `useScreens()` is mounted (`_pollScreens`).
+   *
+   * Public, and the seam for an app that knows before any of those do —
+   * `app.refreshScreens()` publishes whatever the OS says right now.
+   *
+   * **The app's scale is not re-derived.** Every rect this backend speaks
+   * in is points × `app.scale`, fixed at startup, and a window's origin,
+   * an event's coordinates and a surface's pixels all already exist in
+   * that space; moving it under them is a different and much larger change
+   * than re-reading a layout. The layout is converted at the scale the rest
+   * of the app uses, which is what keeps `monitorAt()` answering with the
+   * head a window is actually on (see `screenLayout`).
+   */
+  refreshScreens() {
+    if (this._closed) return false;
+    this._screensAt = performance.now();
+    let screens = null;
+    try {
+      screens = this._native.listScreens?.();
+    } catch {
+      // a bridge going away, or a fake with nothing to say
+      return false;
+    }
+    // An empty answer is "could not tell", never "no displays": a Mac with
+    // the lid shut and no panel attached still has the desk it had, and
+    // publishing nothing would take every monitor out from under
+    // `availableArea` and size the next window against the void.
+    if (!screens?.length) return false;
+    if (sameScreens(screens, this._screens)) return false;
+    this._screens = screens;
+    setScreensForTests(this, screenLayout(screens, this.scale));
+    // A monitor's refresh rate can change under a window that never moved —
+    // a mode switch, a panel woken at 60Hz — and a window's clock is read
+    // from this list rather than kept by the display (`frameIntervalFor`).
+    for (const wnd of this._windows.values()) {
+      if (!wnd.destroyed) wnd._refreshFrameInterval?.();
+    }
+    return true;
+  }
+
+  /**
+   * The layout, re-read at most once every `SCREEN_RECHECK_MS`.
+   *
+   * For the signals that mean "something about the desk may have moved"
+   * rather than "it did": a window reporting its position, which a drag
+   * reports every frame and a display change reports once. Plugging a
+   * monitor in moves the windows that were on it, so this is the one place
+   * the OS does tell us something — it just does not say what.
+   */
+  _recheckScreens() {
+    if (performance.now() - this._screensAt < SCREEN_RECHECK_MS) return false;
+    return this.refreshScreens();
+  }
+
+  /**
+   * The layout on a clock, while something is subscribed to it.
+   *
+   * `useScreens()` says it re-renders when a monitor is plugged in or
+   * unplugged and when the arrangement changes. On X11 that is a RandR
+   * event; here there is nothing to wait for, so while a component is
+   * watching, this asks every `cocoa.screenPoll` ms — on an unref'd timer,
+   * which never holds the process open and never wakes an app that is
+   * waiting on nothing else. An app that never calls `useScreens()` pays
+   * nothing at all: the paths where a stale layout is visible ask for
+   * themselves.
+   *
+   * Started and stopped by the session as the first subscriber arrives and
+   * the last one leaves (`setScreenPolling`), so a hook that unmounts takes
+   * the clock with it.
+   */
+  _pollScreens(on) {
+    if (this._screenTimer) {
+      clearInterval(this._screenTimer);
+      this._screenTimer = null;
+    }
+    if (!on || this._closed || !(this._screenPoll > 0)) return;
+    this._screenTimer = setInterval(
+      () => this.refreshScreens(),
+      this._screenPoll,
+    );
+    this._screenTimer.unref?.();
+  }
+
   /**
    * How often `wnd` may paint, in ms: the explicit `frameInterval` when the
    * root was given one, else the period of the screen under the window's
@@ -570,8 +703,12 @@ export class CocoaApp {
     this._native.setDockBadge(label == null ? null : String(label));
   }
 
-  /** The menu behind a right-click on the Dock icon — `useDockMenu()`. */
-  setDockMenu(items) {
+  /**
+   * The menu behind a right-click on the launcher icon — `useLauncherMenu()`.
+   * Here the launcher is the Dock, which is why the AppKit call below keeps
+   * its own name: `_native.setDockMenu` *is* what Apple calls it.
+   */
+  setLauncherMenu(items) {
     this._dockMenu.update(items);
   }
 
@@ -1140,6 +1277,10 @@ export class CocoaApp {
   _routeGeometry(ev) {
     const wnd = this._window(ev);
     if (!wnd || wnd.destroyed) return;
+    // Before the window re-paces itself against the screen list below: a
+    // display plugged in or removed moves the windows that were on it, and
+    // this is the only thing the bridge says about it (`_recheckScreens`).
+    this._recheckScreens();
     wnd._nativeResized(ev);
     wnd.emit('resize', {
       width: wnd.width,
@@ -1375,6 +1516,7 @@ export class CocoaApp {
     this._pump = null;
     if (this._frameTimer) clearTimeout(this._frameTimer);
     this._frameTimer = null;
+    this._pollScreens(false);
     this._cocoaGL?.destroy();
     this._cocoaGL = null;
     this._unsubscribe?.();
@@ -1413,6 +1555,12 @@ export class CocoaApp {
  * *width* as a bound to every other head: a second display wider than the
  * built-in had its right edge pulled in by the difference, and every
  * anchored popup that reached past it was clamped back (issue #453).
+ *
+ * **Everything the bridge says about a screen comes through**, not only its
+ * rects. `primary` and the panel's refresh rate were dropped here, so
+ * `useScreens().primary` read null on macOS — every entry `primary: false`
+ * — and `refreshRate` null beside a `frameIntervalFor` that was pacing
+ * windows on that very number (#617).
  */
 export function screenLayout(screens, scale) {
   const rect = (r) => ({
@@ -1423,9 +1571,17 @@ export function screenLayout(screens, scale) {
   });
   const primary = screens?.[0];
   return {
-    monitors: (screens ?? []).map((screen) => ({
+    monitors: (screens ?? []).map((screen, i) => ({
       ...rect(screen),
       ...(screen.visible ? { visible: rect(screen.visible) } : null),
+      // `NSScreen.screens[0]` **is** the primary — the screen with the menu
+      // bar, which is where macOS puts a window that names no position —
+      // and the bridge flags it as well; the index is the same fact for a
+      // bridge that does not.
+      primary: screen.primary ?? i === 0,
+      // `NSScreen.maximumFramesPerSecond`, as `fps`. 0 is the OS declining
+      // to say (before macOS 12), which is `useScreens()`'s null.
+      refreshRate: screen.fps > 0 ? screen.fps : null,
     })),
     // Still published for `useScreens().workArea`, which is one rect for
     // the desktop by definition; the primary's is the closest macOS has.
@@ -1433,6 +1589,48 @@ export function screenLayout(screens, scale) {
   };
 }
 
+/**
+ * Whether two `listScreens()` answers describe the same desk.
+ *
+ * Every field the layout is built from, in the order they arrived — which
+ * is `NSScreen.screens`, so the order is the arrangement and the primary,
+ * and a change in it is a change. `fps` counts because a window's frame
+ * clock is read from it, and `scale` because a screen that switched mode
+ * is not the screen it was even at the same size.
+ *
+ * Pure, and exported for that reason: it decides whether a re-read
+ * re-renders every `useScreens()` subscriber, and a poll that publishes an
+ * unchanged layout twice a second is a render loop rather than a fix.
+ */
+export function sameScreens(a, b) {
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (
+      x.x !== y.x ||
+      x.y !== y.y ||
+      x.width !== y.width ||
+      x.height !== y.height ||
+      x.scale !== y.scale ||
+      x.fps !== y.fps ||
+      x.primary !== y.primary ||
+      !sameRect(x.visible, y.visible)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Two `visible` rects, either of which a bridge may not have reported. */
+function sameRect(a, b) {
+  if (!a || !b) return !a === !b;
+  return (
+    a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
+  );
+}
+
 /**
  * Build the app and seed the platform stores the way the mock seeds them —
  * `beginScale`/`beginScreens`/`beginCompositing` find a session already

package/src/cocoa/fonts.js

@@ -846,7 +846,7 @@ export class CocoaFontManager {
   }
 
   /**
-   * The CTFont a glyph run draws with (`CocoaContext2D.drawGlyphs`): a face
+   * The CTFont a glyph run draws with (`BackendContext2D.drawGlyphs`): a face
    * of this engine's at the run's size, or an ntk `Font` — `openFont()`'s —
    * resolved to CoreText from the same bytes, so the glyph ids it shaped
    * with hold. Null for anything else, and the run is skipped.

package/src/cocoa/overlay.js

@@ -14,7 +14,7 @@
 // `map`, `unmap`, `getContext`, `destroy` — plus `present`, which puts what
 // was painted on the layer: ntk blits an X window's backing store on its
 // own, where a layer's contents are a copy the bitmap has to be pushed to.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 export const OVERLAY_Z = 1e7 + 1;
 
@@ -115,7 +115,7 @@ export class CocoaOverlayPane {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {

package/src/cocoa/panewindow.js

@@ -14,7 +14,7 @@
 // via emit. Geometry and input arrive as channel messages (the host owns
 // layout and hit-testing — this is CPU offloading, not isolation), and the
 // only outbound traffic is pane-present.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 let nextPaneId = 1;
 
@@ -183,7 +183,7 @@ export class CocoaPaneWindow {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {

package/src/cocoa/presenter.js

@@ -30,7 +30,7 @@ import { Node } from '../nodes/node.js';
 import { addDamageRect, damageToPaint } from '../nodes/damage.js';
 import { intersectRects } from '../nodes/rects.js';
 import { EASING_CONTROL_POINTS, TRANSITION_CONTROL_POINTS } from '../styles.js';
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 export const RASTER_PAD = 2; // antialiasing/italic overhang outside the ink bounds
 
@@ -431,7 +431,7 @@ export class RasterState {
       this.height = height;
       this.gen++;
       if (!this.ctx) {
-        this.ctx = new CocoaContext2D(
+        this.ctx = new BackendContext2D(
           presenter.native,
           () => this.surface,
           () => this.gen,

package/src/cocoa/surface.js

@@ -6,7 +6,7 @@
 // buffer the same way on both backends and names neither:
 //
 //   const surface = new Surface(app, { width, height });   // device pixels
-//   const ctx = surface.getContext('2d');                    // a CocoaContext2D
+//   const ctx = surface.getContext('2d');                    // a BackendContext2D
 //   ctx.fillRect(0, 0, width, height);
 //   surface.copyWithin({ x: 0, y: 0, width, height }, 0, -rowHeight);
 //   windowCtx.drawImage(surface, x, y);                      // one composite
@@ -43,7 +43,7 @@
 // one from `contentBox()` numbers, which are device pixels already
 // (docs/scale.md). The bridge is told the app's scale so the bitmap carries
 // it — inert for a `drawImage` source, right for a layer's contents.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 
 export class CocoaSurface {
   constructor(app, { width, height, format = 'argb32' } = {}) {
@@ -113,7 +113,7 @@ export class CocoaSurface {
 
   _context() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._handle(),
         () => 1,

package/src/cocoa/window.js

@@ -6,7 +6,7 @@
 // an X window — attributes, reported width/height, event coordinates,
 // _screenOrigin. The divide-by-scale into Cocoa points happens against the
 // native layer and nowhere above it.
-import { CocoaContext2D } from './context2d.js';
+import { BackendContext2D } from '../backend/context2d.js';
 import { CocoaDropTransport, dragSpec } from './dnd.js';
 import { CocoaLayerPresenter } from './presenter.js';
 import { CocoaPromotion } from './promotion.js';
@@ -794,7 +794,7 @@ export class CocoaWindow {
 
   getContext() {
     if (!this._ctx) {
-      this._ctx = new CocoaContext2D(
+      this._ctx = new BackendContext2D(
         this._native,
         () => this._ensureSurface(),
         () => {

package/src/events.js

@@ -113,6 +113,27 @@ class SyntheticEvent {
     this.ctrlKey = Boolean(native?.buttons & MOD.Control);
     this.altKey = Boolean(native?.buttons & MOD.Alt);
     this.metaKey = Boolean(native?.buttons & MOD.Super);
+    // Where the pointer is on the **virtual screen**, in the same logical
+    // pixels `x`/`y` are in — the DOM's name for the DOM's quantity, and the
+    // one an app should reach for when it places something outside the
+    // window (a context menu at the pointer, a drag preview).
+    //
+    // `nativeEvent.rootx`/`rooty` is X11's name for it, is still there, and
+    // is still in *device* pixels: the same split as `ev.x` against
+    // `nativeEvent.x`. Defined exactly where the backend reported a position
+    // — an X11 KeyPress carries one too, so this is not pointer-events-only —
+    // and absent otherwise, because a made-up 0 would read as the screen's
+    // top-left corner rather than as "no answer".
+    if (native?.rootx !== undefined && native?.rootx !== null) {
+      // The **window's** scale, not the target's. `x`/`y` are in the target's
+      // unit on purpose, so a subtree zoomed by a `scale` prop reads its own
+      // — but a screen coordinate is not in that subtree's space at all, and
+      // dividing it by a zoom factor would put it somewhere nobody is. The
+      // drag events have always computed it this way (src/dnd.js).
+      const screen = manager.scale;
+      this.screenX = native.rootx / screen;
+      this.screenY = (native.rooty ?? 0) / screen;
+    }
     this.defaultPrevented = false;
     this.propagationStopped = false;
     if (extra) Object.assign(this, extra);

package/src/foreignnodes.js

@@ -192,10 +192,15 @@ export class ForeignNode extends Node {
    */
   _refuse() {
     this._refused = true;
+    // Named by the capability, not by the backend that happens to have it.
+    // An app cannot act on "use X11", and a second backend growing embedding
+    // would make that wording wrong as well as unhelpful; what an app *can*
+    // act on is the question the last sentence names (AGENTS.md,
+    // "Vocabulary").
     const err = new Error(
-      'react-x11: <foreign> needs the X11 backend — this one has no ' +
-        'cross-process window embedding, so nothing can be put in it. Ask ' +
-        "useSupports('embedding') before rendering one.",
+      'react-x11: <foreign> needs a backend with cross-process window ' +
+        'embedding, and this one has none — so nothing can be put in it. ' +
+        "Ask useSupports('embedding') before rendering one.",
     );
     this.error = err;
     // The client is the whole reason this node is a Tab stop by default, and

package/src/frame/index.js

@@ -44,6 +44,7 @@ import React, {
 } from 'react';
 
 import { useAppOrNull } from '../appcontext.js';
+import { canEmbed } from '../embedding.js';
 import { FrameEnv } from './env.js';
 import { CallbackTable, PROTOCOL } from './protocol.js';
 
@@ -221,11 +222,14 @@ export function Frame({
   ref,
 }) {
   const env = useContext(FrameEnv);
-  // A backend that composites panes from shared memory (Cocoa) declares
-  // itself with createPaneHost; everything else embeds the pane's real
-  // window through <foreign>, exactly as before.
+  // A backend that composites panes from a shared buffer (Cocoa, Windows)
+  // declares itself with createPaneHost; everything else embeds the pane's
+  // real window through <foreign>, exactly as before.
   const appOrNull = useAppOrNull();
   const paneApp = appOrNull?.createPaneHost ? appOrNull : null;
+  // Two mechanisms, one question: is there any way to *show* a pane here?
+  // Asked before the fork rather than after it — see the session effect.
+  const canShowPane = Boolean(paneApp) || canEmbed(appOrNull);
   const [state, setState] = useState({
     phase: 'starting',
     windowId: null,
@@ -262,6 +266,28 @@ export function Frame({
       setState({ phase: 'failed', windowId: null, error });
     };
 
+    // Before the fork, not after it. A backend with neither mechanism used
+    // to start the pane, let it load its module and mount, and only then
+    // discover at the embed that there was nowhere to put it — a whole
+    // process spawned and killed to reach a conclusion the app object had
+    // all along. The fallback it renders is the same one either way; what
+    // changes is that it renders at once and costs nothing.
+    if (!canShowPane) {
+      fail(
+        Object.assign(
+          new Error(
+            'react-x11: <Frame> needs a backend that can show a pane — one ' +
+              'that composites panes from a shared buffer, or one with ' +
+              'cross-process window embedding — and this one has neither, ' +
+              'so no pane was started. Ask ' +
+              "useSupports('embedding') before rendering one.",
+          ),
+          { phase: 'embed' },
+        ),
+      );
+      return undefined;
+    }
+
     let t;
     try {
       t = makeTransport({ src: source, display });
@@ -396,7 +422,7 @@ export function Frame({
       // ask, and everything is unref'd so nothing holds the host open
       if (session.current === s) session.current = null;
     };
-  }, [source, display, generation, makeTransport]);
+  }, [source, display, generation, makeTransport, canShowPane]);
 
   // One update per commit that changed the pane's inputs, props and env in
   // the same message — so a theme flip and the state change that caused it