react-x11 2.16.0 → 2.16.1

package/package.json

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

package/src/acceleratorhooks.js

@@ -11,6 +11,35 @@ import { useEffect, useMemo, useRef } from 'react';
 import { matchesShortcut } from './accelerators.js';
 import { useTopLevelWindow } from './windowid.js';
 
+/**
+ * A binding whose anchor resolved to nothing binds nothing — there is no
+ * event manager to register it with, and the effect runs once, so it will
+ * not come back. Silent, that is a shortcut that simply never fires, with
+ * the tree, the chord and the handler all looking correct (issue #616).
+ *
+ * Once per process, in development: the mistake is structural, and an app
+ * that made it once made it for every chord it declares.
+ */
+let warnedAboutAnchor = false;
+export function resetAcceleratorWarningForTests() {
+  warnedAboutAnchor = false;
+}
+
+function warnUnanchored() {
+  if (process.env.NODE_ENV === 'production' || warnedAboutAnchor) return;
+  warnedAboutAnchor = true;
+  console.warn(
+    'react-x11: a shortcut was bound in a component with no window to hang ' +
+      'it off, so it is bound to nothing and will never fire. By default a ' +
+      "binding belongs to the tree's top-level <window> or, in an app with " +
+      'none, the root-level <popup> holding the keyboard. Anchor it ' +
+      'explicitly with `scope`:\n' +
+      '  const here = useRef(null);\n' +
+      "  useAccelerator([['space']], onToggle, { scope: here });\n" +
+      '  return <box ref={here}>…</box>;',
+  );
+}
+
 /**
  * Bind a chord for as long as this component is mounted, anchored at
  * `anchorRef` — the node the binding belongs to, which is what decides
@@ -30,7 +59,10 @@ export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
   useEffect(() => {
     if (!enabled) return undefined;
     const manager = anchorRef.current?.root?.events;
-    if (!manager) return undefined;
+    if (!manager) {
+      warnUnanchored();
+      return undefined;
+    }
     return manager.registerAccelerator({
       anchor: () => anchorRef.current ?? null,
       handle: (ev) => live.current?.(ev) ?? false,
@@ -52,11 +84,13 @@ export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
  * The handler is called with the key event, and the key is consumed.
  *
  * By default the binding belongs to the window the component is in, which is
- * what an application-wide shortcut wants. Two options for when it is not:
- * `enabled: false` unbinds it without unmounting anything, and `scope` takes
- * a ref to a node the binding hangs off instead — the way to give a modal
- * `<Dialog>` a shortcut of its own, since a binding on the window behind it
- * is one the modal has taken the keyboard from.
+ * what an application-wide shortcut wants — or, in an app with no `<window>`
+ * at all, to the root-level `<popup>` that took the keyboard, which is the
+ * whole of a tray popover's UI (`useTopLevelWindow`). Two options for when
+ * that is not it: `enabled: false` unbinds it without unmounting anything,
+ * and `scope` takes a ref to a node the binding hangs off instead — the way
+ * to give a modal `<Dialog>` a shortcut of its own, since a binding on the
+ * window behind it is one the modal has taken the keyboard from.
  */
 export function useAccelerator(shortcut, handler, options = {}) {
   const { enabled = true, scope } = options;

package/src/anchor.js

@@ -148,7 +148,20 @@ export function deviceAnchorArea(node) {
   if (!app) return null;
   const at = screenRect(node);
   const s = node.scale ?? 1;
-  return availableArea(app, at ? { x: at.x * s, y: at.y * s } : null);
+  // The whole rect, not its corner: a window straddling two monitors has
+  // nodes on each, and the monitor a node is on is the one it covers most of
+  // (`monitorAt`, src/screens.js).
+  return availableArea(
+    app,
+    at
+      ? {
+          x: at.x * s,
+          y: at.y * s,
+          width: at.width * s,
+          height: at.height * s,
+        }
+      : null,
+  );
 }
 
 /**
@@ -248,7 +261,12 @@ export function anchorScreenRect(app, rect, options = {}) {
     width: (rect.width ?? 0) * s,
     height: (rect.height ?? 0) * s,
   };
-  const area = app ? availableArea(app, { x: anchor.x, y: anchor.y }) : null;
+  // The monitor is picked from the whole rect rather than its top-left
+  // corner, because a tray item's frame is not inside its own display: a
+  // menu-bar button reports a rect that starts a few points above the top
+  // edge, and the corner alone lands on whichever display happens to reach
+  // up past it — a different one, on a desk with a taller head (#618).
+  const area = app ? availableArea(app, anchor) : null;
   return placeAgainst(anchor, anchor, area, s, options);
 }
 

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';
@@ -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 —
@@ -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
@@ -1140,6 +1273,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 +1512,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 +1551,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 +1567,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 +1585,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/index.d.ts

@@ -233,7 +233,15 @@ export interface RootOptions {
    * `resizeWait` is how long, in ms, AppKit may hold a live-resize tick for
    * the app's frame at the new size under `react-x11/cocoa-main`, where
    * the frame is painted on another thread (50 by default; 0 lets the edge
-   * move without waiting). `appName` is what the Dock, ⌘-Tab and the app menu print for
+   * move without waiting).
+   * `screenPoll` is how often the screen layout is re-read while a
+   * {@link useScreens} subscriber is mounted, in ms — 500 by default, 0 for
+   * never. macOS has no event for a display plugged in, unplugged or
+   * rearranged that reaches a client, so a component watching the layout is
+   * kept current by asking; an app that never calls `useScreens` never
+   * polls, and the paths where a stale layout would misplace a window ask
+   * for themselves whatever this says.
+   * `appName` is what the Dock, ⌘-Tab and the app menu print for
    * an unbundled process (a bundle's Info.plist wins); `activationPolicy`
    * is `'regular'` (a Dock tile, a ⌘-Tab entry — the default),
    * `'accessory'` (a menu-bar app: windows but no tile) or `'prohibited'`,
@@ -253,6 +261,7 @@ export interface RootOptions {
     frameInterval?: number;
     pumpInterval?: number;
     resizeWait?: number;
+    screenPoll?: number;
     appName?: string;
     activationPolicy?: 'regular' | 'accessory' | 'prohibited';
     exitOnQuit?: boolean;

package/src/keysymchars.js

@@ -0,0 +1,47 @@
+// Generated by scripts/keysym-chars.mjs from X11's keysymdef.h — do not edit.
+//
+// The character each legacy keysym produces, run-length encoded: a run is
+// `<keysym>:<codePoint>` in hex, or `<keysym>+<n>:<codePoint>` where the
+// next n keysyms carry the next n code points. `charOf` (src/keysyms.js)
+// expands it once, on first use. One line per keysymdef.h block, because that
+// is how the header is organised and how a regeneration reads as a diff.
+//
+// Latin-1 and the Unicode keysym form are rules rather than entries and are
+// not in here; neither is any keysym whose character is a control character,
+// which is a key that types nothing.
+export const KEYSYM_CHAR_RUNS = [
+  // Latin-2 (0x01xx), 57 keysyms
+  '1a1:104 1a2:2d8 1a3:141 1a5:13d 1a6:15a 1a9:160 1aa:15e 1ab:164 1ac:179 1ae:17d 1af:17b 1b1:105 1b2:2db 1b3:142 1b5:13e 1b6:15b 1b7:2c7 1b9:161 1ba:15f 1bb:165 1bc:17a 1bd:2dd 1be:17e 1bf:17c 1c0:154 1c3:102 1c5:139 1c6:106 1c8:10c 1ca:118 1cc:11a 1cf:10e 1d0:110 1d1:143 1d2:147 1d5:150 1d8:158 1d9:16e 1db:170 1de:162 1e0:155 1e3:103 1e5:13a 1e6:107 1e8:10d 1ea:119 1ec:11b 1ef:10f 1f0:111 1f1:144 1f2:148 1f5:151 1f8:159 1f9:16f 1fb:171 1fe:163 1ff:2d9',
+  // Latin-3 (0x02xx), 22 keysyms
+  '2a1:126 2a6:124 2a9:130 2ab:11e 2ac:134 2b1:127 2b6:125 2b9:131 2bb:11f 2bc:135 2c5:10a 2c6:108 2d5:120 2d8:11c 2dd:16c 2de:15c 2e5:10b 2e6:109 2f5:121 2f8:11d 2fd:16d 2fe:15d',
+  // Latin-4 (0x03xx), 35 keysyms
+  '3a2:138 3a3:156 3a5:128 3a6:13b 3aa:112 3ab:122 3ac:166 3b3:157 3b5:129 3b6:13c 3ba:113 3bb:123 3bc:167 3bd:14a 3bf:14b 3c0:100 3c7:12e 3cc:116 3cf:12a 3d1:145 3d2:14c 3d3:136 3d9:172 3dd:168 3de:16a 3e0:101 3e7:12f 3ec:117 3ef:12b 3f1:146 3f2:14d 3f3:137 3f9:173 3fd:169 3fe:16b',
+  // Katakana (0x04xx), 64 keysyms
+  '47e:203e 4a1:3002 4a2+1:300c 4a4:3001 4a5:30fb 4a6:30f2 4a7:30a1 4a8:30a3 4a9:30a5 4aa:30a7 4ab:30a9 4ac:30e3 4ad:30e5 4ae:30e7 4af:30c3 4b0:30fc 4b1:30a2 4b2:30a4 4b3:30a6 4b4:30a8 4b5+1:30aa 4b7:30ad 4b8:30af 4b9:30b1 4ba:30b3 4bb:30b5 4bc:30b7 4bd:30b9 4be:30bb 4bf:30bd 4c0:30bf 4c1:30c1 4c2:30c4 4c3:30c6 4c4:30c8 4c5+5:30ca 4cb:30d2 4cc:30d5 4cd:30d8 4ce:30db 4cf+4:30de 4d4:30e4 4d5:30e6 4d6+5:30e8 4dc:30ef 4dd:30f3 4de+1:309b',
+  // Arabic (0x05xx), 48 keysyms
+  '5ac:60c 5bb:61b 5bf:61f 5c1+25:621 5e0+18:640',
+  // Cyrillic (0x06xx), 95 keysyms
+  '6a1+1:452 6a3:451 6a4+8:454 6ad:491 6ae+1:45e 6b0:2116 6b1+1:402 6b3:401 6b4+8:404 6bd:490 6be+1:40e 6c0:44e 6c1+1:430 6c3:446 6c4+1:434 6c6:444 6c7:433 6c8:445 6c9+7:438 6d1:44f 6d2+3:440 6d6:436 6d7:432 6d8:44c 6d9:44b 6da:437 6db:448 6dc:44d 6dd:449 6de:447 6df:44a 6e0:42e 6e1+1:410 6e3:426 6e4+1:414 6e6:424 6e7:413 6e8:425 6e9+7:418 6f1:42f 6f2+3:420 6f6:416 6f7:412 6f8:42c 6f9:42b 6fa:417 6fb:428 6fc:42d 6fd:429 6fe:427 6ff:42a',
+  // Greek (0x07xx), 71 keysyms
+  '7a1:386 7a2+2:388 7a5:3aa 7a7:38c 7a8:38e 7a9:3ab 7ab:38f 7ae:385 7af:2015 7b1+3:3ac 7b5:3ca 7b6:390 7b7+1:3cc 7b9:3cb 7ba:3b0 7bb:3ce 7c1+16:391 7d2:3a3 7d4+5:3a4 7e1+16:3b1 7f2:3c3 7f3:3c2 7f4+5:3c4',
+  // Technical (0x08xx), 42 keysyms
+  '8a1:23b7 8a2:250c 8a3:2500 8a4+1:2320 8a6:2502 8a7:23a1 8a8+1:23a3 8aa:23a6 8ab:239b 8ac+1:239d 8ae:23a0 8af:23a8 8b0:23ac 8bc:2264 8bd:2260 8be:2265 8bf:222b 8c0:2234 8c1+1:221d 8c5:2207 8c8:223c 8c9:2243 8cd:21d4 8ce:21d2 8cf:2261 8d6:221a 8da+1:2282 8dc+1:2229 8de+1:2227 8ef:2202 8f6:192 8fb+3:2190',
+  // Special (0x09xx), 23 keysyms
+  '9e0:25c6 9e1:2592 9e2:2409 9e3+1:240c 9e5:240a 9e8:2424 9e9:240b 9ea:2518 9eb:2510 9ec:250c 9ed:2514 9ee:253c 9ef+1:23ba 9f1:2500 9f2+1:23bc 9f4:251c 9f5:2524 9f6:2534 9f7:252c 9f8:2502',
+  // Publishing (0x0axx), 80 keysyms
+  'aa1:2003 aa2:2002 aa3+1:2004 aa5+3:2007 aa9:2014 aaa:2013 aac:2423 aae:2026 aaf:2025 ab0+7:2153 ab8:2105 abb:2012 abc:27e8 abd:2e abe:27e9 ac3+3:215b ac9:2122 aca:2613 acc:25c1 acd:25b7 ace:25cb acf:25af ad0+1:2018 ad2+1:201c ad4:211e ad5:2030 ad6+1:2032 ad9:271d adb:25ac adc:25c0 add:25b6 ade:25cf adf:25ae ae0:25e6 ae1:25ab ae2:25ad ae3:25b3 ae4:25bd ae5:2606 ae6:2022 ae7:25aa ae8:25b2 ae9:25bc aea:261c aeb:261e aec:2663 aed:2666 aee:2665 af0:2720 af1+1:2020 af3:2713 af4:2717 af5:266f af6:266d af7:2642 af8:2640 af9:260e afa:2315 afb:2117 afc:2038 afd:201a afe:201e',
+  // APL (0x0bxx), 19 keysyms
+  'ba3:3c ba6:3e ba8:2228 ba9:2227 bc0:af bc2:22a4 bc3:2229 bc4:230a bc6:5f bca:2218 bcc:2395 bce:22a5 bcf:25cb bd3:2308 bd6:222a bd8:2283 bda:2282 bdc:22a3 bfc:22a2',
+  // Hebrew (0x0cxx), 28 keysyms
+  'cdf:2017 ce0+26:5d0',
+  // Thai (0x0dxx), 84 keysyms
+  'da1+57:e01 dde+15:e3e df0+9:e50',
+  // Korean (0x0exx), 91 keysyms
+  'ea1+50:3131 ed4+26:11a8 eef:316d ef0:3171 ef1:3178 ef2:317f ef3:3181 ef4:3184 ef5:3186 ef6+1:318d ef8:11eb ef9:11f0 efa:11f9 eff:20a9',
+  // Latin-8 and Latin-9 (0x13xx), 3 keysyms
+  '13bc+1:152 13be:178',
+  // Currency (0x20xx), 1 keysyms
+  '20ac:20ac',
+  // the keypad (0xffxx), 18 keysyms
+  'ff80:20 ffaa+15:2a ffbd:3d',
+];

package/src/keysyms.d.ts

@@ -9,9 +9,27 @@
  */
 export function keysymOf(char: string): number;
 
-/** The character a keysym produces, or `''` for a non-printing key. */
+/**
+ * The character a keysym produces, or `''` for a key that types nothing — a
+ * modifier, a function key, an arrow, or a dead key waiting for the letter it
+ * decorates. Latin-1 and the Unicode form are rules; the legacy blocks a real
+ * keymap is written in — Cyrillic, Greek, Latin-2/3/4, Arabic, Hebrew, Thai,
+ * the keypad, `EuroSign` — come out of a generated table.
+ */
 export function charOf(keysym: number): string;
 
+/**
+ * The uppercase of a keysym, answered in the spelling the keysym was written
+ * in: `й` (`0x6ca`) uppercases to `Й` (`0x6ea`) and not to the Unicode-form
+ * spelling of the same letter. A keysym with no case comes back unchanged.
+ * This is how Caps Lock capitalises.
+ *
+ * `'ß'.toUpperCase()` is `'SS'` — two characters, where a key has one to give
+ * — so the first code point is what comes back: `S`. Same for `fi` and the
+ * polytonic Greek letters whose uppercase is a sequence.
+ */
+export function keysymToUpper(keysym: number): number;
+
 /**
  * The letter of a Ctrl chord, independent of Shift — the keysym for its
  * lowercase form, so `keysymOf('z')` matches both Ctrl+Z and Ctrl+Shift+Z.

package/src/keysyms.js

@@ -5,13 +5,28 @@
 // `ev.keysym`. The full X11 set is several thousand names; this is the part
 // a GUI actually handles, plus the rule for everything else.
 //
-// Two facts make the long tail unnecessary:
+// Two rules cover most of it:
 //
 // - **Latin-1 is identity.** For U+0020 to U+00FF the keysym *is* the code
 //   point, so `'a'` is `0x61` and `'é'` is `0xe9`. That is the whole ASCII
 //   and Latin-1 range, no table needed.
-// - **Everything else is `0x01000000 + codePoint`.** That is the Unicode
-//   keysym rule, and `keysymOf` below applies both.
+// - **The Unicode form is `0x01000000 + codePoint`.** That is what `keysymOf`
+//   below produces for everything outside Latin-1.
+//
+// What the two rules do *not* cover is the **legacy keysym blocks**, and a
+// real keymap is written in them: Cyrillic is `0x6xx`, Greek `0x7xx`,
+// Latin-2/3/4 `0x1xx`–`0x3xx`, Hebrew `0x8xx`, Arabic `0x5xx`, `EuroSign` is
+// `0x20ac` and the keypad digits are `0xffbx`. Those are a table, and it is
+// `src/keysymchars.js` — generated from X11's `keysymdef.h`, which is where
+// libxkbcommon's own table comes from (`scripts/keysym-chars.mjs`).
+//
+// It is only `charOf` that needs it. On X11 ntk supplies the code point and
+// this function is never reached; the Wayland backend decodes the keymap
+// itself (`src/wayland/xkb.js`) and is the first caller that needs `charOf`
+// to be complete, which is why a Russian, Greek or Czech layout typed
+// nothing at all and AltGr+E produced no Euro sign.
+
+import { KEYSYM_CHAR_RUNS } from './keysymchars.js';
 
 /** The keysym for a single character, by the two rules above. */
 export function keysymOf(char) {
@@ -21,13 +36,97 @@ export function keysymOf(char) {
   return 0x01000000 + code;
 }
 
-/** The character a keysym produces, or `''` for a non-printing key. */
+/**
+ * The legacy blocks, expanded once on first use — keysym -> code point, and
+ * the way back. The reverse direction is what keeps a case map inside the
+ * block it started in: `keysymToUpper(Cyrillic_shorti)` is `Cyrillic_SHORTI`
+ * and not the Unicode-form spelling of the same letter, which is the answer
+ * a keymap's own keysyms can be compared against.
+ */
+let legacyChars;
+let legacyKeysyms;
+function expandLegacy() {
+  if (legacyChars) return;
+  legacyChars = new Map();
+  legacyKeysyms = new Map();
+  for (const line of KEYSYM_CHAR_RUNS)
+    for (const run of line.split(' ')) {
+      const [keysyms, cp] = run.split(':');
+      const [first, span] = keysyms.split('+');
+      const from = parseInt(first, 16);
+      const to = parseInt(cp, 16);
+      for (let i = 0; i <= (span ? +span : 0); i++) {
+        legacyChars.set(from + i, to + i);
+        // The eleven code points two blocks both spell — box drawing, a few
+        // set operators, `.` — keep the first, so the answer is stable.
+        if (!legacyKeysyms.has(to + i)) legacyKeysyms.set(to + i, from + i);
+      }
+    }
+}
+function legacyChar(keysym) {
+  expandLegacy();
+  return legacyChars.get(keysym);
+}
+
+/**
+ * The character a keysym produces, or `''` for a key that types nothing —
+ * a modifier, a function key, an arrow, or a dead key waiting for the letter
+ * it decorates.
+ *
+ * "Types nothing" includes the keys whose code point is a control character:
+ * `keysymdef.h` gives BackSpace U+0008 and Delete U+007F, and a text field
+ * that inserted those would be inserting a control byte rather than deleting
+ * anything. The same goes for the unassigned 0x7f–0x9f stretch of the
+ * Latin-1 range, which is not a keysym at all.
+ */
 export function charOf(keysym) {
-  if (keysym >= 0x20 && keysym <= 0xff) return String.fromCodePoint(keysym);
-  if (keysym >= 0x01000100 && keysym <= 0x0110ffff) {
-    return String.fromCodePoint(keysym - 0x01000000);
+  if (keysym >= 0x20 && keysym <= 0x7e) return String.fromCodePoint(keysym);
+  if (keysym >= 0xa0 && keysym <= 0xff) return String.fromCodePoint(keysym);
+  if (keysym >= 0x01000000 && keysym <= 0x0110ffff) {
+    const cp = keysym - 0x01000000;
+    return cp >= 0x20 && cp !== 0x7f ? String.fromCodePoint(cp) : '';
+  }
+  const cp = legacyChar(keysym);
+  return cp === undefined ? '' : String.fromCodePoint(cp);
+}
+
+/**
+ * The uppercase of a keysym, staying in the block it came from — `й`
+ * (`0x6ca`) uppercases to `Й` (`0x6ea`) and not to the Unicode-form spelling
+ * of the same letter. A keysym with no case comes back unchanged.
+ *
+ * This is how Caps Lock capitalises. It is not a lookup of an uppercase
+ * sibling level on the same key: French AZERTY's `é` key is `[é, 2, ~, ˘]`,
+ * where level 2 is a digit, and German's AltGr `ſ` has no sibling at all —
+ * there is no key anywhere with `ſ` and `S` next to each other.
+ *
+ * `'ß'.toUpperCase()` is **`'SS'`**, two characters, and a keyboard has one
+ * key's worth of character to answer with, so the first code point is what
+ * comes back: `S`. libxkbcommon's narrower table says `ẞ` (U+1E9E) there, and
+ * the same goes for `ΐ` and `ΰ`, which it leaves alone. Those three are the
+ * whole of the disagreement, and `S` is the more useful of the two answers
+ * for a key that is about to insert a character.
+ */
+export function keysymToUpper(keysym) {
+  const ch = charOf(keysym);
+  if (!ch) return keysym;
+  const upper = ch.toUpperCase();
+  if (upper === ch) return keysym;
+  const cp = upper.codePointAt(0);
+  if (cp === ch.codePointAt(0)) return keysym;
+  expandLegacy();
+  // Answer in the spelling the keysym was written in. A keymap that uses the
+  // legacy blocks gets a legacy keysym back — `й` is `Й` (`0x6ea`), not the
+  // Unicode-form spelling of the same letter — and so does Latin-1, where
+  // AltGr's `µ` uppercases to `Greek_MU`. A keysym already written in the
+  // Unicode form keeps it, because that is the block *it* chose. The two
+  // spell the same character either way; what differs is whether the answer
+  // can be compared against the keysyms the keymap itself carries.
+  if (keysym < 0x01000000) {
+    const legacy = legacyKeysyms.get(cp);
+    if (legacy !== undefined) return legacy;
   }
-  return '';
+  return keysymOf(String.fromCodePoint(cp));
 }
 
 // --- editing and navigation ------------------------------------------------

package/src/screens.js

@@ -119,6 +119,11 @@ class ScreenSession {
     this._desktopAtom = null;
     this._snapshot = null;
     this._listeners = new Set();
+    /** A backend that has to be *asked* for its layout rather than told —
+     *  see `setScreenPolling`. `_revalidate` re-reads it now; `_watched` is
+     *  told whether anything is subscribed. */
+    this._revalidate = null;
+    this._watched = null;
     /** Every `X.on('event')` handler installed here, so `stop()` can take
      *  them off again rather than leaving one per root on a shared client. */
     this._handlers = [];
@@ -138,7 +143,11 @@ class ScreenSession {
       }
     }
     this._handlers.length = 0;
+    const watched = this._listeners.size > 0;
     this._listeners.clear();
+    if (watched) this._watch(false);
+    this._revalidate = null;
+    this._watched = null;
   }
 
   /** Install an X event handler that this session owns. */
@@ -183,32 +192,35 @@ class ScreenSession {
 
   subscribe(fn) {
     this._listeners.add(fn);
-    return () => this._listeners.delete(fn);
+    if (this._listeners.size === 1) this._watch(true);
+    return () => {
+      if (!this._listeners.delete(fn)) return;
+      if (!this._listeners.size) this._watch(false);
+    };
   }
-}
 
-/** The monitor a point is on, or the largest one when it is on none (a
- *  window whose owner the WM has not placed yet, or coordinates from a
- *  screen layout that has since changed). */
-function monitorAt(monitors, point) {
-  if (!monitors?.length) return null;
-  if (point) {
-    for (const m of monitors) {
-      if (
-        point.x >= m.x &&
-        point.x < m.x + m.width &&
-        point.y >= m.y &&
-        point.y < m.y + m.height
-      ) {
-        return m;
-      }
+  /** Ask a pulled backend to re-read the layout, now. Synchronous: the
+   *  callers are placement paths with no round trip available to them. */
+  revalidate() {
+    if (!this._revalidate || this.stopped) return;
+    try {
+      this._revalidate();
+    } catch {
+      // a backend that cannot answer leaves the layout it published
+      // standing, which is a better answer than none
     }
   }
-  let best = monitors[0];
-  for (const m of monitors) {
-    if (m.width * m.height > best.width * best.height) best = m;
+
+  /** Whether anything is subscribed, for a backend that only has to keep
+   *  asking while someone is listening. */
+  _watch(on) {
+    if (!this._watched) return;
+    try {
+      this._watched(on);
+    } catch {
+      // as above: its clock, its problem
+    }
   }
-  return best;
 }
 
 /** The overlap of two rects, or `null` where they do not touch. */
@@ -221,6 +233,82 @@ function intersect(a, b) {
   return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
 }
 
+/** How far apart two rects are, squared: zero where they meet, and the gap
+ *  between their nearest edges otherwise. Squared because nothing compares
+ *  it against a length — only against another of these. */
+function gapSquared(a, b) {
+  const dx = Math.max(a.x - (b.x + b.width), b.x - (a.x + a.width), 0);
+  const dy = Math.max(a.y - (b.y + b.height), b.y - (a.y + a.height), 0);
+  return dx * dx + dy * dy;
+}
+
+/** The biggest monitor there is — the stand-in for "the one you look at",
+ *  for a question with no position in it at all. */
+function largestMonitor(monitors) {
+  let best = monitors[0];
+  for (const m of monitors) {
+    if (m.width * m.height > best.width * best.height) best = m;
+  }
+  return best;
+}
+
+/**
+ * The monitor `near` is on. `near` is a rect in screen coordinates, and a
+ * point is the 1x1 rect at it — the same containment a point used to get,
+ * since a 1x1 rect overlaps exactly the monitor that contains its corner.
+ *
+ * **The one it overlaps most**, because one corner of a rect does not say
+ * which monitor the rect is on. A menu-bar item's frame starts a few points
+ * *above* the top of its own display, and on a desk where another display
+ * reaches down past that edge, the corner alone is inside the *other*
+ * monitor — or inside none — and the popup opens there (#618). Every rect
+ * that has a size knows better than its corner does.
+ *
+ * **The nearest one**, by the gap between the rects, when it overlaps none.
+ * A rect that is off every monitor is nearly always just outside one of
+ * them — that same menu-bar furniture, a pointer at the very edge, a window
+ * the WM has not placed yet — and the nearest monitor is the only answer
+ * that has anything to do with where it was. The largest was the old answer
+ * and it can be anywhere on the desk.
+ *
+ * With no position at all (`near` null — an auto-sized window with no owner
+ * to open beside), the largest monitor, which is all there is to go on.
+ */
+function monitorAt(monitors, near) {
+  if (!monitors?.length) return null;
+  if (!near) return largestMonitor(monitors);
+  // A degenerate rect counts as its own thinnest real version, the way
+  // `anchorOffscreen` reads a caret: a point is 1x1, and so is a rect whose
+  // size nobody filled in.
+  const rect = {
+    x: near.x,
+    y: near.y,
+    width: near.width > 1 ? near.width : 1,
+    height: near.height > 1 ? near.height : 1,
+  };
+  let best = null;
+  let most = 0;
+  for (const m of monitors) {
+    const over = intersect(m, rect);
+    const area = over ? over.width * over.height : 0;
+    if (area > most) {
+      best = m;
+      most = area;
+    }
+  }
+  if (best) return best;
+  let nearest = monitors[0];
+  let least = Infinity;
+  for (const m of monitors) {
+    const gap = gapSquared(m, rect);
+    if (gap < least) {
+      nearest = m;
+      least = gap;
+    }
+  }
+  return nearest;
+}
+
 /**
  * The usable part of one monitor.
  *
@@ -262,12 +350,19 @@ function usable(monitor, work) {
 
 /**
  * The rect an auto-sized window may grow into, or `null` where there is
- * nothing to ask. `near` is a screen-coordinate point the window will open
- * next to — a `transientFor` owner's origin, in practice — and picks the
- * monitor when there are several.
+ * nothing to ask. `near` is a screen-coordinate **rect** the window will
+ * open against — a `transientFor` owner's origin, the node a popup hangs
+ * off, the tray item a click reported — and picks the monitor when there
+ * are several (`monitorAt`); `{x, y}` alone is a point.
  */
 export function availableArea(app, near = null) {
   const session = sessions.get(app);
+  // The monitor a popup is flipped and clamped into is picked here, so a
+  // backend whose layout is pulled rather than pushed is asked *now*
+  // rather than answered from whatever it last read (`setScreenPolling`).
+  // A rect the desk has since moved lands inside another monitor's stale
+  // one, and the popup opens at that monitor's edge (#617).
+  session?.revalidate();
   const screen = session?.screenRect ?? null;
   if (!session) return screen;
   const monitor = monitorAt(session.monitors, near) ?? screen;
@@ -364,6 +459,46 @@ export function watchScreens(app, fn) {
   return session.subscribe(fn);
 }
 
+/**
+ * Register a backend whose layout has to be **pulled**.
+ *
+ * X11 and Wayland are told: RandR sends an event, a `wl_output` announces
+ * itself, and a `publish` lands from the handler. The cocoa bridge keeps
+ * its `NSScreen` copy current on macOS's own
+ * `NSApplicationDidChangeScreenParametersNotification` but emits no event
+ * for it, so there a display plugged in, rearranged or made primary is a
+ * question nobody asked (#617). This is where the asking is wired up:
+ *
+ * - `revalidate()` re-reads the layout and publishes any change. Called
+ *   before `availableArea()` picks the monitor a window is sized against
+ *   or a popup is clamped into, which is where a stale rect does visible
+ *   damage, and synchronous for that reason.
+ * - `watched(on)` is told when the *first* subscriber arrives and when the
+ *   last one leaves. A change nobody asked about still has to reach
+ *   `useScreens()`, which needs a clock where there is no event — and a
+ *   clock that only runs while a component is watching costs an app that
+ *   never asks nothing at all.
+ *
+ * Both are optional, and a session with neither behaves exactly as it did:
+ * this adds no work to the X11 path.
+ */
+export function setScreenPolling(
+  app,
+  { revalidate = null, watched = null } = {},
+) {
+  let session = sessions.get(app);
+  if (!session) {
+    session = new ScreenSession(app);
+    sessions.set(app, session);
+  }
+  session._revalidate = revalidate;
+  session._watched = watched;
+  // Registered after a `useScreens()` already mounted — the backend still
+  // has to hear that it is being watched.
+  if (watched && session._listeners.size) session._watch(true);
+  return session;
+}
+
 // --------------------------------------------------------------------------
 // Starting up
 // --------------------------------------------------------------------------

package/src/types/events.d.ts

@@ -541,6 +541,11 @@ export interface AcceleratorOptions {
  * matched against the Latin keysym so a layout switch does not turn it off,
  * and behind whatever a focused element consumed with `preventDefault()`.
  * See docs/events.md.
+ *
+ * With no `scope` the binding belongs to the tree's top-level `<window>`, or,
+ * in an app that has none, to the root-level `<popup>` holding the keyboard —
+ * a tray popover. One that can reach neither binds nothing and says so once
+ * in development.
  */
 export function useAccelerator(
   shortcut: MenuShortcut,

package/src/types/filedialog.d.ts

@@ -162,7 +162,9 @@ export interface FileDialogs {
  *
  * Exact when the tree has one top-level window, which is nearly every app.
  * With several it prefers the focused one and warns in development when it
- * has to guess — see docs/filedialog.md.
+ * has to guess; with none — a menu-bar app, which is a tray item and a
+ * popover — it answers the root-level `<popup>` that took the keyboard. See
+ * docs/filedialog.md.
  */
 export declare function useTopLevelWindow(): {
   readonly current: NtkWindow | DrawnNode | null;

package/src/wayland/xkb.js

@@ -19,8 +19,10 @@
 //   xkb_symbols    `key <AD01> { [ q, Q ] };`     keycode -> keysyms per level,
 //                  with `symbols[Group2]`/`symbols[2]` and `type=` where given
 //                  `modifier_map Mod5 { <LVL3> }` real modifier -> keycodes
-//   xkb_compat     `interpret ISO_Level3_Shift { virtualModifier= LevelThree; }`
-//                                                keysym -> virtual modifier
+//   xkb_compat     `interpret ISO_Level3_Shift { virtualModifier= LevelThree;
+//                     useModMapMods= level1; }`  keysym -> virtual modifier,
+//                                                and which of a key's symbols
+//                                                may name it
 //
 // From the last two, a virtual modifier like `LevelThree` resolves to the
 // real modifier bit the compositor will actually report in
@@ -29,8 +31,10 @@
 // that does not say.
 //
 // What is not read: key actions (the compositor applies those; we only see
-// their effect in the modifier state), indicators, geometry, and the
-// per-type `preserve` rules.
+// their effect in the modifier state), indicators and geometry. The per-type
+// `preserve` rules *are* read, for the one thing they decide here: whether
+// Caps Lock still has a capitalisation to do after the type has chosen a
+// level (`_capitalises`).
 //
 // The output is two things. `keycode2keysyms` is the X core shape —
 // `[g1l1, g1l2, g2l1, g2l2, …]` — because that is what `keyboard.js`'s
@@ -38,7 +42,7 @@
 // `decode()` is the full answer, using the key's real type so that level 3
 // and 4 (AltGr) resolve where the two-level core shape cannot express them.
 
-import { charOf } from '../keysyms.js';
+import { charOf, keysymToUpper } from '../keysyms.js';
 import { keysymFromName } from './keysymnames.js';
 
 /** Real modifier bits, as X and XKB both number them. */
@@ -135,7 +139,7 @@ export class XkbKeymap {
     while ((m = re.exec(s))) {
       const body = balanced(s, m.index + m[0].length - 1);
       re.lastIndex = m.index + m[0].length + body.length;
-      const type = { name: m[1], mods: [], map: [], levels: 1 };
+      const type = { name: m[1], mods: [], map: [], preserve: [], levels: 1 };
       const mods = body.match(/modifiers\s*=\s*([^;]+);/);
       if (mods)
         type.mods = mods[1]
@@ -153,6 +157,17 @@ export class XkbKeymap {
         type.map.push({ set, level });
         if (level > type.levels) type.levels = level;
       }
+      // `preserve[Lock+LevelThree]= Lock;` — the modifiers this state does
+      // *not* consume, which is the whole of whether Caps Lock still applies
+      // on a key whose type otherwise swallows Lock.
+      for (const e of body.matchAll(/preserve\[([^\]]+)\]\s*=\s*([^;]+);/gi)) {
+        const split = (x) =>
+          x
+            .split('+')
+            .map((y) => y.trim())
+            .filter((y) => y && y !== 'none' && y !== 'None');
+        type.preserve.push({ set: split(e[1]), kept: split(e[2]) });
+      }
       for (const e of body.matchAll(/level_name\[(?:Level)?(\d+)\]/gi)) {
         if (+e[1] > type.levels) type.levels = +e[1];
       }
@@ -161,6 +176,10 @@ export class XkbKeymap {
   }
 
   _parseCompat(s) {
+    // `interpret.useModMapMods= AnyLevel;` — the section default, which every
+    // keymap states, and which an interpretation overrides for itself.
+    const dflt = s.match(/interpret\.useModMapMods\s*=\s*([A-Za-z0-9_]+)/i);
+    const level1 = (word) => /^level(?:1|One)$/i.test(word ?? '');
     // interpret <keysym>[+cond] { virtualModifier= X; ... }
     const re = /interpret\s+([A-Za-z0-9_]+)(?:\+[^{]*)?\s*\{/g;
     let m;
@@ -170,7 +189,12 @@ export class XkbKeymap {
       const vm = body.match(/virtualModifier\s*=\s*([A-Za-z0-9_]+)/i);
       if (!vm) continue;
       const sym = keysymFromName(m[1]);
-      if (sym) (this._interp ??= new Map()).set(sym, vm[1]);
+      if (!sym) continue;
+      const umm = body.match(/useModMapMods\s*=\s*([A-Za-z0-9_]+)/i);
+      (this._interp ??= new Map()).set(sym, {
+        vmod: vm[1],
+        level1Only: level1(umm ? umm[1] : dflt?.[1]),
+      });
     }
   }
 
@@ -256,24 +280,51 @@ export class XkbKeymap {
   }
 
   /**
-   * Virtual modifier -> real modifier: the keys whose keysym `interpret`
-   * binds to the virtual modifier are looked up in `modifier_map`, and the
-   * real bits found there are the answer.
+   * Virtual modifier -> real modifier: a key's `interpret`ed keysyms name the
+   * virtual modifiers the key sets, and the key's `modifier_map` bits are
+   * what those virtual modifiers turn out to mean.
+   *
+   * Which of a key's keysyms may name one is `useModMapMods`, and it is the
+   * whole of AltGr working. `<RALT>` sits in `modifier_map Mod1` beside the
+   * other Alt keys and *also* carries `ISO_Level3_Shift`, on a secondary
+   * group or a second level:
+   *
+   *     key <RALT> { type= "ONE_LEVEL", symbols[1]= [ Alt_R ],
+   *                                     symbols[2]= [ ISO_Level3_Shift ] };
+   *     modifier_map Mod1 { <LALT>, <RALT>, <ALT>, <META> };
+   *     modifier_map Mod5 { <LVL3> };
+   *
+   * Attributing a key's bits to every keysym on it collected Mod1 from
+   * `<RALT>` on top of Mod5 from `<LVL3>`, so `LevelThree` resolved to
+   * `Mod1|Mod5` — and since `_levelFor` matches the masked state for
+   * equality, a real AltGr press (Mod5 alone) never reached level 3. AltGr
+   * did nothing and the third and fourth level of every layout were
+   * unreachable. `useModMapMods= level1`, which is what the keymap says for
+   * `ISO_Level3_Shift`, means a key contributes only where the keysym is its
+   * **primary** symbol — group 1, level 1 — and `<RALT>`'s primary symbol is
+   * `Alt_R`, so it never should have contributed.
    */
   _resolveVmods() {
-    const bySym = new Map(); // keysym -> real mask, from modmap via symbols
+    const bind = (vmod, bits) =>
+      this.vmods.set(vmod, (this.vmods.get(vmod) ?? 0) | bits);
     for (const [code, key] of this.keys) {
       const bits = this.modmap.get(code);
       if (!bits) continue;
-      for (const g of key.groups)
-        for (const sym of g?.syms ?? [])
-          if (sym) bySym.set(sym, (bySym.get(sym) ?? 0) | bits);
+      for (let gi = 0; gi < key.groups.length; gi++) {
+        const syms = key.groups[gi]?.syms ?? [];
+        for (let li = 0; li < syms.length; li++) {
+          const interp = syms[li] && this._interp?.get(syms[li]);
+          if (!interp) continue;
+          if (interp.level1Only && (gi || li)) continue;
+          bind(interp.vmod, bits);
+        }
+      }
     }
-    for (const { sym, bit } of this._modmapSyms ?? [])
-      bySym.set(sym, (bySym.get(sym) ?? 0) | bit);
-    for (const [sym, vmod] of this._interp ?? []) {
-      const real = bySym.get(sym);
-      if (real) this.vmods.set(vmod, (this.vmods.get(vmod) ?? 0) | real);
+    // `modifier_map Shift { Shift_L };` — the bare-keysym form names no key,
+    // so there is no level to test it against.
+    for (const { sym, bit } of this._modmapSyms ?? []) {
+      const interp = this._interp?.get(sym);
+      if (interp) bind(interp.vmod, bit);
     }
     for (const [name, bit] of Object.entries(VMOD_FALLBACK)) {
       if (!this.vmods.has(name)) this.vmods.set(name, bit);
@@ -286,6 +337,13 @@ export class XkbKeymap {
     return this.vmods.get(name) ?? 0;
   }
 
+  /** A list of modifier names as one real mask. */
+  _maskOf(names) {
+    let mask = 0;
+    for (const name of names) mask |= this._modMask(name);
+    return mask;
+  }
+
   /**
    * The X core keyboard mapping — two keysyms per group, up to four groups —
    * which is what `GetKeyboardMapping` would have answered.
@@ -319,17 +377,37 @@ export class XkbKeymap {
    */
   _levelFor(type, mods) {
     if (!type) return mods & REAL_MODS.Shift ? 1 : 0;
-    let relevant = 0;
-    for (const m of type.mods) relevant |= this._modMask(m);
+    const relevant = this._maskOf(type.mods);
     const masked = mods & relevant;
     for (const { set, level } of type.map) {
-      let want = 0;
-      for (const m of set) want |= this._modMask(m);
-      if (want === masked) return level - 1;
+      if (this._maskOf(set) === masked) return level - 1;
     }
     return 0;
   }
 
+  /**
+   * Whether Caps Lock still has a capitalisation to do.
+   *
+   * XKB's rule: Lock is effective, and the key's type did not **consume** it.
+   * A type that names Lock among its modifiers consumed it — `ALPHABETIC`'s
+   * `map[Lock]= 2` has already picked the level Caps Lock wanted, and
+   * capitalising on top would be doing it twice. Unless the type says
+   * otherwise: `preserve[Lock+LevelThree]= Lock` hands Lock back, which is how
+   * German's AltGr levels capitalise (`ſ` -> `S`) while its Shift levels,
+   * reached through `map[Lock]`, do not.
+   */
+  _capitalises(type, mods) {
+    if (!(mods & REAL_MODS.Lock)) return false;
+    if (!type) return true;
+    const relevant = this._maskOf(type.mods);
+    if (!(relevant & REAL_MODS.Lock)) return true;
+    const masked = mods & relevant;
+    for (const { set, kept } of type.preserve)
+      if (this._maskOf(set) === masked)
+        return (this._maskOf(kept) & REAL_MODS.Lock) !== 0;
+    return false;
+  }
+
   /**
    * Decode a key event.
    *
@@ -349,31 +427,17 @@ export class XkbKeymap {
     let level = this._levelFor(g.type, mods);
     if (level >= g.syms.length || !g.syms[level]) {
       // Lock on a one-level key, or Shift on a key with no upper level:
-      // fall back the way the core protocol does — the first symbol,
-      // uppercased when it has a case.
+      // fall back the way the core protocol does, to the first symbol. Any
+      // capitalisation it has coming is the separate step below.
       level = 0;
     }
     let keysym = g.syms[level] ?? 0;
-    // Caps Lock on a plain two-level alphabetic key whose type does not
-    // fold Lock (a keymap with only "TWO_LEVEL" for letters): X core rule.
-    if (
-      level === 0 &&
-      mods & REAL_MODS.Lock &&
-      g.syms.length >= 2 &&
-      !(mods & REAL_MODS.Shift)
-    ) {
-      const lower = charOf(g.syms[0]);
-      const upper = charOf(g.syms[1]);
-      if (
-        lower &&
-        upper &&
-        lower !== upper &&
-        lower.toUpperCase() === upper &&
-        g.type?.mods?.includes('Lock') === false
-      ) {
-        keysym = g.syms[1];
-      }
-    }
+    // Caps Lock capitalises the keysym the type already chose, rather than
+    // reaching for an uppercase sibling level. Pairing levels works for
+    // `[a, A]` and nothing else: AZERTY's `é` key is `[é, 2, ~, ˘]`, where
+    // level 2 is a digit, and German's AltGr `ſ` has no sibling at all — so
+    // `é`, `à`, `è`, `ç`, `ù` and every Cyrillic letter stayed lowercase.
+    if (this._capitalises(g.type, mods)) keysym = keysymToUpper(keysym);
     if (!keysym) return undefined;
     const ch = charOf(keysym);
     const codepoint = ch ? ch.codePointAt(0) : undefined;
@@ -398,24 +462,71 @@ export class XkbKeymap {
 }
 
 /**
- * The type XKB assigns a key that names none: one symbol is ONE_LEVEL, two
- * are ALPHABETIC when they are a case pair and TWO_LEVEL otherwise, four are
- * FOUR_LEVEL(_ALPHABETIC / _SEMIALPHABETIC).
+ * `XkbKSIsKeypad`: the one run of keysyms the keypad produces, `KP_Space`
+ * through `KP_Equal`. Every keypad key is in it on both of its levels — the
+ * navigation keysym (`KP_Home`) as much as the digit (`KP_7`).
+ */
+function isKeypad(sym) {
+  return sym >= 0xff80 && sym <= 0xffbd;
+}
+
+/**
+ * `XkbKSIsLower` and `XkbKSIsUpper`: a keysym has a case, and is the lower or
+ * the upper one of the pair.
+ *
+ * Two independent questions rather than one pairing — which is the same
+ * mistake `decode()` used to make about Caps Lock, in the one other place it
+ * was made. German's `s` is `[s, S, ſ, ẞ]`, and `ſ` does not *pair* with `ẞ`
+ * (`'ſ'.toUpperCase()` is `'S'`), but `ſ` is a lowercase letter and `ẞ` is an
+ * uppercase one, which is all the type ladder asks. Pairing them made the key
+ * FOUR_LEVEL_SEMIALPHABETIC, whose `preserve[Lock+LevelThree]` hands Lock back
+ * — so Caps+AltGr capitalised a level that was already capital.
+ */
+function isLower(sym) {
+  const ch = charOf(sym);
+  return !!ch && ch.toLowerCase() === ch && ch.toUpperCase() !== ch;
+}
+function isUpper(sym) {
+  const ch = charOf(sym);
+  return !!ch && ch.toUpperCase() === ch && ch.toLowerCase() !== ch;
+}
+
+/**
+ * The type XKB assigns a key that names none — xkbcomp's `FindAutomaticType`,
+ * which libxkbcommon inherits. Two symbols are ALPHABETIC when they are a
+ * case pair, **KEYPAD when either of them is a keypad keysym**, and TWO_LEVEL
+ * otherwise; three or four are the FOUR_LEVEL family along the same ladder.
+ *
+ * The keypad rung is not decoration: libxkbcommon writes the keypad bare —
+ * `key <KP7> { [ KP_Home, KP_7 ] };` — so *every* keypad key lands here, and
+ * `[KP_Home, KP_7]` is not a case pair. Without the rung it fell through to
+ * TWO_LEVEL, whose `map[Shift]= 2` puts the digit on Shift and leaves NumLock
+ * with nothing to do, which inverted the whole keypad: the digits typed
+ * `KP_Home`/`KP_Up`/`KP_End` and moved the cursor, and holding Shift is what
+ * produced a number. The keymap's own KEYPAD type — `modifiers= Shift+NumLock;
+ * map[NumLock]= 2;` — is the one that belongs.
  */
 function implicitType(syms) {
-  const n = syms.filter(Boolean).length;
+  // The width is the length of the list with only *trailing* NoSymbols
+  // trimmed, which is how libxkbcommon counts it. A NoSymbol in the middle
+  // is a level that types nothing, not an absent one: counting the non-zero
+  // entries instead made `key <ALT> { [ NoSymbol, Alt_L ] };` a one-level key
+  // whose only level was NoSymbol, so <ALT>, <META>, <SUPR> and <HYPR>
+  // decoded to nothing in every modifier state.
+  let n = syms.length;
+  while (n > 0 && !syms[n - 1]) n--;
   if (n <= 1) return 'ONE_LEVEL';
-  const casePair = (a, b) => {
-    const la = charOf(a);
-    const lb = charOf(b);
-    return la && lb && la !== lb && la.toUpperCase() === lb;
-  };
-  if (n === 2) return casePair(syms[0], syms[1]) ? 'ALPHABETIC' : 'TWO_LEVEL';
-  if (casePair(syms[0], syms[1]))
-    return casePair(syms[2], syms[3])
+  const cased = (a, b) => isLower(a) && isUpper(b);
+  const keypad = isKeypad(syms[0]) || isKeypad(syms[1]);
+  if (n === 2) {
+    if (cased(syms[0], syms[1])) return 'ALPHABETIC';
+    return keypad ? 'KEYPAD' : 'TWO_LEVEL';
+  }
+  if (cased(syms[0], syms[1]))
+    return cased(syms[2], syms[3])
       ? 'FOUR_LEVEL_ALPHABETIC'
       : 'FOUR_LEVEL_SEMIALPHABETIC';
-  return 'FOUR_LEVEL';
+  return keypad ? 'FOUR_LEVEL_KEYPAD' : 'FOUR_LEVEL';
 }
 
 /** Everything from `//` or `#` to the end of the line, outside strings. */

package/src/windowid.js

@@ -105,8 +105,54 @@ export function topLevelWindows(app) {
   );
 }
 
+/**
+ * The root-level `<popup>`s this connection is currently rendering — the
+ * half `topLevelWindows()` leaves out, in the order they were added.
+ *
+ * Only interesting when there are no top-level windows at all: a menu-bar
+ * app whose whole UI is a popover a tray click opens has no `<window>` for
+ * anything to belong to, and the popup *is* the top of that tree
+ * (`useTopLevelWindow`). With a window in the tree these stay out of it, for
+ * the reason they are out of `topLevelWindows()` — override-redirect is
+ * never what a dialog should be transient for.
+ */
+function rootLevelPopups(app) {
+  if (!app) return [];
+  return (app._rootChildren ?? []).filter(
+    (node) => node?.isWindow && node.isPopup && node.window?.id,
+  );
+}
+
 let warnedAboutAmbiguity = false;
 
+/**
+ * One of several candidates, on the inference `useTopLevelWindow` documents:
+ * one is exact, uniquely focused wins, and anything else is the most
+ * recently opened plus a development warning that says so.
+ */
+function pickOwner(candidates, what) {
+  if (candidates.length <= 1) return candidates[0] ?? null;
+
+  const focused = candidates.filter((w) => w.events?.windowFocused);
+  if (focused.length === 1) return focused[0];
+
+  // Nothing separates them. `windowFocused` also defaults to true on an
+  // ntk too old to report focus changes, so "all of them" is the same
+  // answer as "none of them" and both land here.
+  if (process.env.NODE_ENV !== 'production' && !warnedAboutAmbiguity) {
+    warnedAboutAmbiguity = true;
+    console.warn(
+      `react-x11: this tree has ${candidates.length} ${what}, none of them ` +
+        'uniquely focused, so the owner window is a guess (the most ' +
+        'recently opened). Pass the window explicitly to be exact:\n' +
+        '  const win = useRef(null);\n' +
+        '  const { openFile } = useFileDialog({ parentWindow: win });\n' +
+        '  return <window ref={win}>…</window>;',
+    );
+  }
+  return candidates[candidates.length - 1];
+}
+
 /**
  * The window a component belongs to, resolved when it is read.
  *
@@ -134,6 +180,13 @@ let warnedAboutAmbiguity = false;
  * - several with nothing to separate them: the most recently opened, and a
  *   development warning naming `parentWindow` as the way to be exact. A
  *   guess that says it is guessing beats a guess that does not.
+ * - **no top-level window at all: the root-level `<popup>` that has the
+ *   keyboard.** A menu-bar app is a tray item and a popover, and nothing
+ *   else — there is no `<window>` for a shortcut, a file dialog or the
+ *   global menu to belong to, and answering `null` made every one of them
+ *   quietly do nothing (issue #616). A `grabKeyboard` popup is where the
+ *   keys are by construction, so it is preferred over one that is merely
+ *   up; among equals the same focus/most-recent inference applies.
  *
  * Returns a **ref-like object** rather than a number: the window is not
  * realized on the first render, so a value read then would be `null` on the
@@ -146,27 +199,16 @@ export function useTopLevelWindow() {
     () => ({
       get current() {
         const windows = topLevelWindows(app);
-        if (windows.length <= 1) return windows[0] ?? null;
-
-        const focused = windows.filter((w) => w.events?.windowFocused);
-        if (focused.length === 1) return focused[0];
+        if (windows.length) return pickOwner(windows, 'top-level windows');
 
-        // Nothing separates them. `windowFocused` also defaults to true on an
-        // ntk too old to report focus changes, so "all of them" is the same
-        // answer as "none of them" and both land here.
-        if (process.env.NODE_ENV !== 'production' && !warnedAboutAmbiguity) {
-          warnedAboutAmbiguity = true;
-          console.warn(
-            `react-x11: this tree has ${windows.length} top-level windows and ` +
-              'none of them is uniquely focused, so the owner window is a ' +
-              'guess (the most recently opened). Pass the window explicitly ' +
-              'to be exact:\n' +
-              '  const win = useRef(null);\n' +
-              '  const { openFile } = useFileDialog({ parentWindow: win });\n' +
-              '  return <window ref={win}>…</window>;',
-          );
-        }
-        return windows[windows.length - 1];
+        // A popup-only tree — the tray popover. Not reached while the app
+        // has a window, so nothing that already worked changes shape.
+        const popups = rootLevelPopups(app);
+        const keyboard = popups.filter((node) => node.props?.grabKeyboard);
+        return pickOwner(
+          keyboard.length ? keyboard : popups,
+          'root-level popups and no window at all',
+        );
       },
     }),
     [app],