react-x11 2.16.0 → 2.17.0

package/src/glnodes.js

@@ -58,9 +58,20 @@ export function glxConfig(app, spec) {
         .chooseGLXConfig(spec)
         .then((config) => ({ backend: 'indirect', ...config }));
     } else {
+      // Which backend is asking decides what the honest answer is. Telling a
+      // Windows user to upgrade ntk sends them after a package that backend
+      // does not use, and an error a developer cannot act on is worse than
+      // the feature simply being absent (AGENTS.md, "An error you hit is an
+      // error an app developer will hit").
       promise = Promise.reject(
         new Error(
-          'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',
+          process.platform === 'win32'
+            ? 'react-x11: <glarea> is not built on the win32 backend yet — it ' +
+                'needs ANGLE (EGL and GLES over Direct3D 11), which ' +
+                'docs/windows.md plans as an optional dependency the way ' +
+                'x11-dri is on X11. Everything else on this backend works ' +
+                'without it; for GL content today, use the X11 backend.'
+            : 'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',
         ),
       );
     }

package/src/idle.js

@@ -186,6 +186,17 @@ class IdleWatcher {
  */
 async function armIdle(watcher) {
   const session = watcher.session;
+
+  // The Windows rung, first because it is the only one there: everything
+  // below this reaches into `app.X`, and a tree that is not on an X server
+  // has none. `GetLastInputInfo` answers for the whole session, which is what
+  // an idle timeout means, so the shape is the polling rung's — with the
+  // answer arriving synchronously instead of over a connection.
+  if (typeof session.app?.lastInputMs === 'function') {
+    pollLastInput(watcher);
+    return;
+  }
+
   const counter = await session.counter();
   if (watcher.stopped) return;
 
@@ -281,6 +292,31 @@ function poll(watcher, saver) {
   });
 }
 
+/**
+ * The same adaptive wait as {@link poll}, over a counter this process can read
+ * without asking anybody: `GetLastInputInfo` is a call, not a round trip.
+ *
+ * The two directions are still asymmetric for the same reason. Not idle yet:
+ * sleep for exactly the remainder. Idle: nothing says when the user will come
+ * back, and no input reaches this process while they are typing in another
+ * window, so poll on an interval scaled to the timeout.
+ */
+function pollLastInput(watcher) {
+  if (watcher.stopped) return;
+  const elapsed = watcher.session.app.lastInputMs?.();
+  if (typeof elapsed !== 'number') return;
+  const idle = elapsed >= watcher.timeout;
+  watcher.set(idle);
+  clearTimeout(watcher._timer);
+  watcher._timer = setTimeout(
+    () => pollLastInput(watcher),
+    idle
+      ? Math.min(30_000, Math.max(1_000, watcher.timeout / 4))
+      : Math.max(250, watcher.timeout - elapsed),
+  );
+  watcher._timer.unref?.();
+}
+
 function schedule(watcher, saver, delay) {
   clearTimeout(watcher._timer);
   watcher._timer = setTimeout(() => poll(watcher, saver), delay);
@@ -364,7 +400,12 @@ export function setIdleForTests(app, timeout, idle) {
  * code and for tests.
  */
 export async function keepAwake({ reason = 'Busy', app = null } = {}) {
-  for (const rung of [portalInhibit, screenSaverInhibit, xInhibit]) {
+  for (const rung of [
+    windowsInhibit,
+    portalInhibit,
+    screenSaverInhibit,
+    xInhibit,
+  ]) {
     try {
       const release = await rung(reason, app);
       if (release) return once(release);
@@ -375,6 +416,23 @@ export async function keepAwake({ reason = 'Busy', app = null } = {}) {
   return () => {};
 }
 
+/**
+ * Rung 0: `SetThreadExecutionState`, on Windows.
+ *
+ * Above the portal rungs because it is the only one a Windows session has,
+ * and below nothing: on a desktop with a portal this returns null on the
+ * first line and costs a property read.
+ *
+ * `reason` is dropped rather than passed. Windows takes no string with the
+ * call — `powercfg /requests` names the process, not a reason — and inventing
+ * somewhere to put it would be pretending the system shows it.
+ */
+async function windowsInhibit(reason, app) {
+  const hold = app?.keepAwake;
+  if (typeof hold !== 'function') return null;
+  return hold.call(app, true);
+}
+
 /** A release that runs once however many times it is called — a double
  *  release would drop somebody else's inhibition on the counted X rung. */
 function once(fn) {

package/src/index.d.ts

@@ -27,6 +27,7 @@ export * from './types/fonts.js';
 export * from './types/system.js';
 export * from './types/capabilities.js';
 export * from './types/launcher.js';
+export * from './types/taskbar.js';
 export * from './types/tray.js';
 export * from './types/permissions.js';
 export * from './types/notifications.js';
@@ -62,6 +63,46 @@ export function useWindowId(
   ref: RefObject<NtkWindow | DrawnNode | null>,
 ): () => number | null;
 
+/**
+ * The handle **another process** embeds to show this window, or `null` where
+ * this backend cannot hand one out.
+ *
+ * The companion to `<window embeddable>`, and deliberately not
+ * {@link windowIdOf}: on X11 the two are the same number, and everywhere
+ * else they are not.
+ *
+ * - **X11** — the window's XID, which means the same thing in every process
+ *   on the display.
+ * - **Windows** — a composition surface handle, already valid in the host
+ *   process. A window cannot be embedded here (a composition target stops
+ *   presenting once its window is a child), so the *buffer* crosses instead
+ *   and the host binds it to a visual of its own. The host is the parent
+ *   process unless `createRoot({ win32: { paneHostPid } })` says otherwise.
+ * - **Anything else** — `null`, which is the capability rather than a
+ *   failure.
+ *
+ * Pass it to the host out of band, as an XID is passed: argv, an environment
+ * variable, a message. What the host does with it differs per platform; what
+ * an app writes to get it does not.
+ */
+export function windowHandleOf(
+  target:
+    | NtkWindow
+    | DrawnNode
+    | RefObject<NtkWindow | DrawnNode | null>
+    | null
+    | undefined,
+): number | null;
+
+/**
+ * `windowHandleOf` bound to a ref. A **getter**, stable across renders, for
+ * {@link useWindowId}'s reason: the window is not realized on the render
+ * that declares it.
+ */
+export function useWindowHandle(
+  ref: RefObject<NtkWindow | DrawnNode | null>,
+): () => number | null;
+
 /**
  * Parse a `text/uri-list` payload (RFC 2483): CRLF-separated,
  * percent-encoded, `#` lines are comments. What `DropEvent.files` is made
@@ -233,7 +274,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 +302,7 @@ export interface RootOptions {
     frameInterval?: number;
     pumpInterval?: number;
     resizeWait?: number;
+    screenPoll?: number;
     appName?: string;
     activationPolicy?: 'regular' | 'accessory' | 'prohibited';
     exitOnQuit?: boolean;

package/src/index.js

@@ -4,7 +4,13 @@ import './bootstrap.js';
 
 export { createRoot, Renderer } from './Reconciler.js';
 export { createStyles, flattenStyle } from './styles.js';
-export { windowIdOf, useWindowId, useTopLevelWindow } from './windowid.js';
+export {
+  windowIdOf,
+  useWindowId,
+  windowHandleOf,
+  useWindowHandle,
+  useTopLevelWindow,
+} from './windowid.js';
 export { launchTimestamp, notifyStartupComplete } from './startup.js';
 export { activateWindow } from './activate.js';
 export { lastInputTime, serverTime } from './inputtime.js';
@@ -14,9 +20,30 @@ export {
   registerApplication,
 } from './application.js';
 export { useAppActivate, useAppOpen } from './apphooks.js';
-export { setBadge, setProgress, setQuicklist, setUrgent } from './launcher.js';
-export { useBadge, useDockMenu, useProgress } from './launcherhooks.js';
+export {
+  setBadge,
+  setLauncherMenu,
+  setProgress,
+  setQuicklist,
+  setUrgent,
+} from './launcher.js';
+export {
+  useBadge,
+  useDockMenu,
+  useLauncherMenu,
+  useProgress,
+} from './launcherhooks.js';
 export { useTray } from './trayhooks.js';
+// The Windows taskbar's own surfaces. Exported unconditionally and inert
+// where the backend has none — `useDesktopCapability('launcher').features`
+// carries `tasks`, `thumbnailToolbar` and `recentDocuments`, so an app
+// branches on what this desktop has rather than on the platform.
+export {
+  noteRecentDocument,
+  useJumpList,
+  useRecentDocument,
+  useThumbnailToolbar,
+} from './taskbarhooks.js';
 export {
   CAPABILITIES,
   NO_CAPABILITY,

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/launcher.js

@@ -6,7 +6,7 @@
 // desktops, two mechanisms, one call each:
 //
 //   1. **the app's own tile** — the cocoa backend's `NSDockTile`, reached
-//      through the app object (`setDockBadge`, `setDockMenu`, src/cocoa/
+//      through the app object (`setDockBadge`, `setLauncherMenu`, src/cocoa/
 //      app.js).
 //   2. **`com.canonical.Unity.LauncherEntry`** over the session bus — the
 //      protocol Unity defined and the KDE, elementary, Cairo-Dock and
@@ -34,13 +34,13 @@
 // is runtime, it follows state, and Dash-to-Dock/ubuntu-dock, Plank and the
 // Unity heritage launchers all render it.
 //
-// So `useDockMenu()` has a Linux rung after all, and the three menus an app
+// So `useLauncherMenu()` has a Linux rung after all, and the three menus an app
 // puts on the desktop — panel, tray, launcher — are now one authoring model
 // on both backends. `.desktop` actions are still the right place for entries
 // that must work *while the app is not running*; they are a different feature
 // wearing a similar hat.
 //
-// Nothing here imports react: `useBadge`/`useDockMenu` (launcherhooks.js) are
+// Nothing here imports react: `useBadge`/`useLauncherMenu` (launcherhooks.js) are
 // the hooks, and these are the functions under them, callable from host-side
 // code with no tree. The entry on the bus is held for as long as anything is
 // shown and released when the last of it is cleared — a held bus ref is a
@@ -300,7 +300,8 @@ export async function setUrgent(urgent, { app } = {}) {
 }
 
 /**
- * The menu behind a right-click on the app's launcher icon — the quicklist.
+ * The menu behind a right-click on the app's launcher icon — the Dock menu on
+ * macOS, the quicklist on Linux.
  *
  * Takes `MenuBar`'s item vocabulary and exports it as a `com.canonical.dbusmenu`
  * tree, exactly as the tray and the global menu do. `null` takes it down.
@@ -310,12 +311,12 @@ export async function setUrgent(urgent, { app } = {}) {
  * launcher that builds its client the instant it sees `quicklist` finds an
  * object there.
  */
-export async function setQuicklist(items, { app } = {}) {
+export async function setLauncherMenu(items, { app } = {}) {
   const target = app ?? soleApp();
 
-  // Rung 1: the app's own tile menu.
-  if (typeof target?.setDockMenu === 'function') {
-    target.setDockMenu(items ?? null);
+  // Rung 1: the app's own icon menu.
+  if (typeof target?.setLauncherMenu === 'function') {
+    target.setLauncherMenu(items ?? null);
     return true;
   }
 
@@ -367,6 +368,14 @@ export async function setQuicklist(items, { app } = {}) {
   return true;
 }
 
+/**
+ * @deprecated Renamed to {@link setLauncherMenu}. "Quicklist" is the Unity
+ * launcher's word for the menu macOS calls the Dock menu; this function
+ * always drove both, and the name only ever named one of them. Kept working
+ * and kept quiet.
+ */
+export const setQuicklist = setLauncherMenu;
+
 /** Test seam, not public: drop the exported entry without emitting. */
 export async function _resetLauncher() {
   await releaseEntry();

package/src/launcherhooks.js

@@ -1,4 +1,4 @@
-// `useBadge()`, `useProgress()` and `useDockMenu()` — the launcher's view of
+// `useBadge()`, `useProgress()` and `useLauncherMenu()` — the launcher's view of
 // the app, as things a component declares rather than manages.
 //
 // All three now have a rung on both backends except progress, which has one
@@ -7,7 +7,7 @@
 // feature an app should branch on, and a development warning for every
 // desktop that lacks one is a warning nobody can act on.
 //
-// The one that changed shape is `useDockMenu`. It used to be cocoa-only on
+// The one that changed shape is `useLauncherMenu`. It used to be cocoa-only on
 // the grounds that the freedesktop counterpart was an install step — see
 // `launcher.js`, where that reasoning is corrected: the launcher protocol
 // carries a `quicklist` dbusmenu, so the Dock menu is runtime code on both.
@@ -15,7 +15,7 @@
 import { useEffect, useRef } from 'react';
 
 import { useAppOrNull } from './appcontext.js';
-import { setBadge, setProgress, setQuicklist } from './launcher.js';
+import { setBadge, setLauncherMenu, setProgress } from './launcher.js';
 
 /**
  * Show `value` on the app's icon while this component is mounted, and clear
@@ -63,12 +63,12 @@ export function useProgress(value) {
 }
 
 /**
- * The menu behind a right-click on the app's icon in the Dock or launcher,
- * from the same `items` vocabulary `MenuBar` and `ContextMenu` take — an
- * item's `onSelect` fires when the user picks it.
+ * The menu behind a right-click on the app's **launcher icon** — the Dock on
+ * macOS, the launcher on Linux — from the same `items` vocabulary `MenuBar`
+ * and `ContextMenu` take. An item's `onSelect` fires when the user picks it.
  *
  * ```jsx
- * useDockMenu([
+ * useLauncherMenu([
  *   { label: 'New Window', onSelect: openWindow },
  *   { type: 'separator' },
  *   { label: 'Recent', items: recent.map(toItem) },
@@ -80,8 +80,14 @@ export function useProgress(value) {
  * backend; the launcher protocol's `quicklist` on Linux, which needs the
  * identity `registerApplication({ appId })` establishes and a `.desktop` file
  * of that name for a launcher to attach it to.
+ *
+ * It reads `useDesktopCapability('launcher').features.menu`, which is where
+ * the name comes from: every desktop has one icon standing for this
+ * application and calls it something different — Dock, taskbar, panel, dash —
+ * and `launcher` is the one word that is none of their words and all of their
+ * meanings (AGENTS.md, "Vocabulary").
  */
-export function useDockMenu(items) {
+export function useLauncherMenu(items) {
   const app = useAppOrNull();
   // read at activation time, so a pick three minutes from now runs the
   // handler from the current render rather than the mounting one
@@ -89,12 +95,20 @@ export function useDockMenu(items) {
   live.current = items;
 
   useEffect(() => {
-    setQuicklist(items ?? null, { app }).catch(() => {});
+    setLauncherMenu(items ?? null, { app }).catch(() => {});
   }, [items, app]);
 
   useEffect(() => {
     return () => {
-      setQuicklist(null, { app }).catch(() => {});
+      setLauncherMenu(null, { app }).catch(() => {});
     };
   }, [app]);
 }
+
+/**
+ * @deprecated Renamed to {@link useLauncherMenu}. "Dock" is one desktop's
+ * word for the icon every desktop has; this hook drove the Linux launcher's
+ * quicklist long before the name caught up. Kept working, and kept quiet —
+ * an alias that warned would punish an app for code that is still correct.
+ */
+export const useDockMenu = useLauncherMenu;

package/src/node.d.ts

@@ -40,7 +40,7 @@ export interface ImageDataLike {
 /**
  * The 2d context a node paints into — the canvas-shaped subset **both**
  * backends implement: ntk's `RenderingContext2D` over XRender on X11, and
- * `CocoaContext2D` over CoreGraphics on macOS. Declared as the contract an
+ * `BackendContext2D` over CoreGraphics on macOS. Declared as the contract an
  * element may rely on rather than as either class: what is here is on
  * both, and a member one backend has and the other does not is optional
  * here or absent. Coordinates are device pixels in the owning window's

package/src/nodes/cascade.js

@@ -422,6 +422,15 @@ export class NodeCascade {
   get placed() {
     const owner = this.isWindow ? this : this.root;
     if (!owner) return false;
+    // A window written under a root `<ThemeProvider>` is handed that palette
+    // when the scope inserts it, which is after it and its subtree were built
+    // and first resolved (nodes/scope.js `insertBefore`). Until then its
+    // ancestry is as incomplete as a popup's without its parent, and every
+    // token the provider defines would be reported as unknown — a warning for
+    // a style that then resolves correctly, and under
+    // `REACT_X11_STRICT_TOKENS=1` a throw that killed an app whose palette was
+    // fine.
+    if (owner._awaitsRootScope && owner._scope == null) return false;
     return owner.isPopup ? owner.parent != null : true;
   }
 

package/src/nodes/node.js

@@ -70,7 +70,12 @@ export class Node {
     return DEVTOOLS_FAKE_DOCUMENT;
   }
 
-  constructor(kind, props, app, { yoga = true } = {}) {
+  constructor(kind, props, app, { yoga = true, awaitsRootScope = false } = {}) {
+    // Set before anything resolves a style: a `<window>`'s own style is
+    // resolved by this constructor, and whether its ancestry is complete
+    // decides whether an unresolved `$token` is reported (cascade.js
+    // `placed`). A window under a root `<ThemeProvider>` has no palette yet.
+    this._awaitsRootScope = awaitsRootScope;
     this.kind = kind;
     this.props = props;
     this.app = app;