react-x11 2.15.3 → 2.16.1

package/src/icontheme.js

@@ -0,0 +1,240 @@
+// The freedesktop icon theme: an icon found by name the way the Icon Theme
+// Specification finds it, for a symbol drawn inside a window on Linux (#591).
+//
+// A theme is a directory of the same name under any of the base directories
+// — `~/.icons`, `$XDG_DATA_HOME/icons`, each `$XDG_DATA_DIRS/icons` — with an
+// `index.theme` saying which of its subdirectories hold which sizes and which
+// themes it inherits from. A lookup tries the user's theme, then everything
+// it inherits, then `hicolor`, the theme every other one falls back on, and
+// last the loose files in `/usr/share/pixmaps`. Inside a theme it takes the
+// first directory whose size matches, and failing that the closest one.
+//
+// The directories are listed rather than probed file by file: one `readdir`
+// per directory, once, answers every name looked up there afterwards, where
+// a `stat` per name per directory per theme is thousands of calls for a
+// toolbar. Both run synchronously, since a layout pass cannot wait — the
+// first lookup in a theme pays for the listing, and later ones are a `Map`.
+
+import * as nodeFs from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** The formats a lookup answers with, in the specification's order. XPM is
+ *  left out: nothing here decodes it. */
+const EXTENSIONS = ['png', 'svg'];
+
+/** Every base directory the specification searches, in its order. */
+export function iconBaseDirs(env = process.env, home = homedir()) {
+  const dataHome = env.XDG_DATA_HOME || join(home, '.local', 'share');
+  const dataDirs = (env.XDG_DATA_DIRS || '/usr/local/share:/usr/share')
+    .split(':')
+    .filter(Boolean);
+  return [
+    join(home, '.icons'),
+    join(dataHome, 'icons'),
+    ...dataDirs.map((dir) => join(dir, 'icons')),
+  ];
+}
+
+/** Where loose icons with no theme live, searched last. */
+export const PIXMAP_DIRS = ['/usr/share/pixmaps'];
+
+/**
+ * `index.theme`'s keys, section by section — the desktop-entry format, which
+ * is an INI file with `#` comments. Values stay strings.
+ */
+export function parseIndexTheme(text) {
+  const sections = new Map();
+  let current = null;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const header = /^\[(.+)\]$/.exec(line);
+    if (header) {
+      current = new Map();
+      sections.set(header[1], current);
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (current && eq > 0) {
+      current.set(line.slice(0, eq).trim(), line.slice(eq + 1).trim());
+    }
+  }
+  return sections;
+}
+
+const list = (value) =>
+  (value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+const int = (value, fallback) => {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+/** One subdirectory's size rules, with the specification's defaults. */
+function directoryRules(keys) {
+  const size = int(keys?.get('Size'), 0);
+  return {
+    size,
+    scale: int(keys?.get('Scale'), 1),
+    type: keys?.get('Type') ?? 'Threshold',
+    minSize: int(keys?.get('MinSize'), size),
+    maxSize: int(keys?.get('MaxSize'), size),
+    threshold: int(keys?.get('Threshold'), 2),
+  };
+}
+
+/** The specification's DirectoryMatchesSize. */
+function matchesSize(dir, size, scale) {
+  if (dir.scale !== scale) return false;
+  if (dir.type === 'Fixed') return dir.size === size;
+  if (dir.type === 'Scalable')
+    return dir.minSize <= size && size <= dir.maxSize;
+  return dir.size - dir.threshold <= size && size <= dir.size + dir.threshold;
+}
+
+/** The specification's DirectorySizeDistance, with its Threshold branch's
+ *  typos read as what they mean: the threshold's bounds, times the scale. */
+function sizeDistance(dir, size, scale) {
+  const want = size * scale;
+  if (dir.type === 'Fixed') return Math.abs(dir.size * dir.scale - want);
+  const low = dir.type === 'Scalable' ? dir.minSize : dir.size - dir.threshold;
+  const high = dir.type === 'Scalable' ? dir.maxSize : dir.size + dir.threshold;
+  if (want < low * dir.scale) return low * dir.scale - want;
+  if (want > high * dir.scale) return want - high * dir.scale;
+  return 0;
+}
+
+/**
+ * Icon lookup in one theme and everything under it. `find(name, size,
+ * scale)` answers an absolute path, or null.
+ */
+export class IconTheme {
+  constructor({
+    theme = 'hicolor',
+    baseDirs = iconBaseDirs(),
+    pixmapDirs = PIXMAP_DIRS,
+    fs = nodeFs,
+  } = {}) {
+    this.theme = theme;
+    this.baseDirs = baseDirs;
+    this.pixmapDirs = pixmapDirs;
+    this.fs = fs;
+    this._themes = new Map(); // name -> { dirs, inherits } | null
+    this._listings = new Map(); // absolute dir -> Set of file names | null
+    this._found = new Map(); // name|size|scale -> path | null
+  }
+
+  find(name, size, scale = 1) {
+    const key = `${name}\u0000${size}\u0000${scale}`;
+    if (this._found.has(key)) return this._found.get(key);
+    const path =
+      this._inTheme(name, size, scale, this.theme, new Set()) ??
+      (this.theme === 'hicolor'
+        ? null
+        : this._inTheme(name, size, scale, 'hicolor', new Set())) ??
+      this._loose(name);
+    this._found.set(key, path);
+    return path;
+  }
+
+  /** FindIconHelper: this theme, then the ones it inherits, depth first. */
+  _inTheme(name, size, scale, theme, seen) {
+    if (seen.has(theme)) return null;
+    seen.add(theme);
+    const index = this._index(theme);
+    if (!index) return null;
+    const found = this._lookup(name, size, scale, theme, index);
+    if (found) return found;
+    for (const parent of index.inherits) {
+      const inherited = this._inTheme(name, size, scale, parent, seen);
+      if (inherited) return inherited;
+    }
+    return null;
+  }
+
+  /** LookupIcon: a directory of the right size, else the closest one. */
+  _lookup(name, size, scale, theme, index) {
+    let closest = null;
+    let distance = Infinity;
+    for (const dir of index.dirs) {
+      const fits = matchesSize(dir.rules, size, scale);
+      const d = fits ? 0 : sizeDistance(dir.rules, size, scale);
+      if (!fits && d >= distance) continue;
+      for (const base of this.baseDirs) {
+        const at = join(base, theme, dir.path);
+        const file = this._fileIn(at, name);
+        if (!file) continue;
+        if (fits) return file;
+        closest = file;
+        distance = d;
+        break;
+      }
+    }
+    return closest;
+  }
+
+  /** The loose files: an icon with no theme at all. */
+  _loose(name) {
+    for (const dir of this.pixmapDirs) {
+      const file = this._fileIn(dir, name);
+      if (file) return file;
+    }
+    return null;
+  }
+
+  _fileIn(dir, name) {
+    const names = this._listing(dir);
+    if (!names) return null;
+    for (const ext of EXTENSIONS) {
+      const file = `${name}.${ext}`;
+      if (names.has(file)) return join(dir, file);
+    }
+    return null;
+  }
+
+  _listing(dir) {
+    if (this._listings.has(dir)) return this._listings.get(dir);
+    let names = null;
+    try {
+      names = new Set(this.fs.readdirSync(dir));
+    } catch {
+      // not there, which is most directories in most base directories
+    }
+    this._listings.set(dir, names);
+    return names;
+  }
+
+  /** A theme's `index.theme`, from the first base directory that has one. */
+  _index(theme) {
+    if (this._themes.has(theme)) return this._themes.get(theme);
+    let index = null;
+    for (const base of this.baseDirs) {
+      let text;
+      try {
+        text = this.fs.readFileSync(join(base, theme, 'index.theme'), 'utf8');
+      } catch {
+        continue;
+      }
+      const sections = parseIndexTheme(text);
+      const head = sections.get('Icon Theme');
+      const names = [
+        ...list(head?.get('Directories')),
+        ...list(head?.get('ScaledDirectories')),
+      ];
+      index = {
+        inherits: list(head?.get('Inherits')),
+        dirs: [...new Set(names)].map((path) => ({
+          path,
+          rules: directoryRules(sections.get(path)),
+        })),
+      };
+      break;
+    }
+    this._themes.set(theme, index);
+    return index;
+  }
+}

package/src/imagesource.js

@@ -44,6 +44,73 @@ export function isPathImageSource(src) {
 export const toLoadablePath = (src) =>
   typeof src === 'string' || src instanceof URL ? src : new URL(src.href);
 
+/**
+ * A symbol by name: `{ symbol, weight?, scale?, variableValue? }` — the
+ * platform's own icons, drawn in the text colour (#591, src/symbols.js). Not
+ * pixels at all, so none of the decoding or caching below applies: the node
+ * asks the platform to draw the name at paint.
+ */
+export function isSymbolImageSource(src) {
+  return (
+    src != null &&
+    typeof src === 'object' &&
+    !(src instanceof Uint8Array) &&
+    'symbol' in src
+  );
+}
+
+const SYMBOL_SCALES = new Set(['small', 'medium', 'large']);
+
+function validateSymbolSource(src) {
+  const at = `react-x11: <image src={{ symbol: ${JSON.stringify(src.symbol)} }}>`;
+  if (typeof src.symbol !== 'string' || src.symbol === '') {
+    throw new Error(
+      `${at} needs a name: an SF Symbol on macOS, like 'speaker.wave.3.fill', ` +
+        "or an icon theme's name on Linux, like 'audio-volume-high'.",
+    );
+  }
+  const { weight, scale, variableValue } = src;
+  if (
+    weight !== undefined &&
+    !(
+      weight === 'normal' ||
+      weight === 'bold' ||
+      (typeof weight === 'number' && weight >= 1 && weight <= 1000)
+    )
+  ) {
+    throw new Error(
+      `${at} has weight ${JSON.stringify(weight)}, expected what fontWeight ` +
+        "takes — 'normal', 'bold' or a number from 1 to 1000.",
+    );
+  }
+  if (scale !== undefined && !SYMBOL_SCALES.has(scale)) {
+    throw new Error(
+      `${at} has scale ${JSON.stringify(scale)}, expected 'small', 'medium' ` +
+        "or 'large'.",
+    );
+  }
+  if (
+    variableValue !== undefined &&
+    !(
+      typeof variableValue === 'number' &&
+      variableValue >= 0 &&
+      variableValue <= 1
+    )
+  ) {
+    throw new Error(
+      `${at} has variableValue ${JSON.stringify(variableValue)}, expected a ` +
+        'number from 0 to 1.',
+    );
+  }
+}
+
+/** Two symbol sources naming the same drawing, however fresh the objects. */
+const sameSymbol = (a, b) =>
+  a.symbol === b.symbol &&
+  a.weight === b.weight &&
+  a.scale === b.scale &&
+  a.variableValue === b.variableValue;
+
 /** Raw straight-RGBA pixels: `{ width, height, data }` — the shape
  * `getImageData` hands back. (A `Buffer` of encoded bytes is a `Uint8Array`
  * subclass, so the two byte forms are one check elsewhere.) */
@@ -54,6 +121,7 @@ export function isRawImageSource(src) {
     !(src instanceof Uint8Array) &&
     !isPathImageSource(src) &&
     !isDirectImageSource(src) &&
+    !isSymbolImageSource(src) &&
     'data' in src
   );
 }
@@ -70,7 +138,8 @@ const describe = (value) =>
 /** Stated once, so every error lists the same set of accepted forms. */
 const SRC_FORMS =
   'a file path or file URL (PNG/JPEG), encoded PNG/JPEG bytes (Buffer or ' +
-  'Uint8Array), raw RGBA ({ width, height, data }), or an ntk Image/Surface';
+  'Uint8Array), raw RGBA ({ width, height, data }), an ntk Image/Surface, ' +
+  "or a symbol by name ({ symbol: 'speaker.wave.3.fill' })";
 
 function validateServerSource(kind, desc) {
   const shape =
@@ -163,6 +232,16 @@ export function validateImageProps(props) {
   if (props.drawable != null) validateServerSource('drawable', props.drawable);
   const src = props.src;
   if (src == null) return;
+  if (isSymbolImageSource(src)) {
+    if (props.cacheKey != null) {
+      throw new Error(
+        'react-x11: <image cacheKey> names decoded pixels, and a symbol is ' +
+          'drawn by name, not decoded — there is nothing to cache. Drop the ' +
+          'cacheKey.',
+      );
+    }
+    return validateSymbolSource(src);
+  }
   if (isPathImageSource(src)) return;
   if (src instanceof Uint8Array) return;
   if (isDirectImageSource(src)) return;
@@ -207,6 +286,9 @@ export function imageSourceChanged(next, prev) {
   if (next.cacheKey !== prev.cacheKey) return true;
   if (next.src === prev.src) return false;
   if ((next.src == null) !== (prev.src == null)) return true;
+  if (isSymbolImageSource(next.src) && isSymbolImageSource(prev.src)) {
+    return !sameSymbol(next.src, prev.src);
+  }
   if (isDirectImageSource(next.src) || isDirectImageSource(prev.src))
     return true;
   return next.cacheKey == null;

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

@@ -93,6 +93,8 @@ export { useKeyboardState } from './keyboardstatehooks.js';
 export { matchesShortcut } from './accelerators.js';
 export { useAccelerator } from './acceleratorhooks.js';
 export { useDesktopSettings } from './desktopsettingshooks.js';
+// what the app itself remembers between launches (#592)
+export { createSettings } from './settings.js';
 export { loadFont, openFont } from './fonts.js';
 export { useFont } from './fonthooks.js';
 export { systemLocale } from './locale.js';
@@ -127,6 +129,7 @@ export {
   useAnchorTracking,
   anchorArea,
   anchorRect,
+  anchorScreenRect,
   centerRect,
   screenRect,
 } from './components/index.js';

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/node.d.ts

@@ -236,6 +236,13 @@ export interface TextStyle {
   variations: Record<string, number> | undefined;
   textRendering: TextRendering | undefined;
   color: string;
+  /** `letterSpacing`, in device pixels like `size` — undefined unless a
+   * style or the cascade above it named one. */
+  letterSpacing: number | undefined;
+  /** The OpenType features `fontVariantNumeric` and `fontFeatureSettings`
+   * resolve to, tag → 1 on, 0 off or an alternate — undefined unless either
+   * was named. The same object for the same pair of values. */
+  features: Readonly<Record<string, number>> | undefined;
 }
 
 /**