react-x11 2.39.0 → 2.40.0

package/src/components/PasswordInput.js

@@ -4,7 +4,7 @@
 
 import React, { useEffect, useRef, useState } from 'react';
 import { createStyles } from '../styles.js';
-import { useClipboard } from '../appcontext.js';
+import { useAppOrNull, useClipboard } from '../appcontext.js';
 import { windowIdOf } from '../windowid.js';
 import { useTheme } from './theme.js';
 import { Icon } from './Icon.js';
@@ -19,6 +19,7 @@ import {
   XK_KP_ENTER,
   XK_RETURN,
   ctrlChordLetter,
+  primaryModifierHeld,
 } from '../keysyms.js';
 
 const h = React.createElement;
@@ -169,6 +170,7 @@ export function PasswordInput({
   const inputRef = useRef(null);
   const hideTimer = useRef(null);
   const clipboard = useClipboard();
+  const app = useAppOrNull();
   const [ownValue, setOwnValue] = useState(defaultValue ?? '');
   const [ownRevealed, setOwnRevealed] = useState(false);
   const [focused, setFocused] = useState(false);
@@ -282,13 +284,16 @@ export function PasswordInput({
       if (ev.shiftKey) paste('CLIPBOARD');
       return;
     }
-    if (ev.ctrlKey) {
+    if (ev.ctrlKey || ev.metaKey) {
       const letter = ctrlChordLetter(ev);
       // Ctrl+U clears the line, as readline and every pinentry on the desktop
-      // do; Ctrl+V pastes. Nothing for C, X or A — there is no selection to
-      // copy, and the secret does not leave by the clipboard.
-      if (letter === CTRL_U) commit('');
-      else if (letter === CTRL_V) paste('CLIPBOARD');
+      // do; Ctrl+V pastes — ⌘V on the Cocoa backend, where ⌃U still clears,
+      // as it does in a Mac terminal. Nothing for C, X or A — there is no
+      // selection to copy, and the secret does not leave by the clipboard.
+      // Any other chord is a command and never a character of the secret.
+      if (letter === CTRL_U && ev.ctrlKey) commit('');
+      else if (letter === CTRL_V && primaryModifierHeld(ev, app))
+        paste('CLIPBOARD');
       return;
     }
     // A printable character and only that: a control code is not text, and

package/src/editmenu.js

@@ -86,6 +86,9 @@ export function editMenuColors(theme) {
 export function editMenuItems(actions = {}, { canPaste = true } = {}) {
   const has = (verb) => typeof actions[verb] === 'function';
   const selected = Boolean(actions.hasSelection);
+  // `Control` is the primary modifier here, as it is in a menu bar's chord:
+  // ⌘ on the Cocoa backend, which is what the editors answer there and what
+  // `editMenuGeometry` prints when it is told so
   const groups = [
     [
       has('undo') && {
@@ -147,8 +150,12 @@ export function editMenuItems(actions = {}, { canPaste = true } = {}) {
  * @param {Array<{id?, label?, shortcut?, type?, enabled?}>} items
  * @param {(text: string) => number|null} [measure] text width, or null when
  *   nothing can be measured yet
+ * @param {number} [scale]
+ * @param {{primary?: 'Control'|'Super'}} [options] the app's primary
+ *   modifier (keysyms.js): `'Super'` prints the shortcuts the Mac way —
+ *   `⌘Z`, `⇧⌘Z` — since ⌘ is what the text controls answer there
  */
-export function editMenuGeometry(items, measure, scale = 1) {
+export function editMenuGeometry(items, measure, scale = 1, { primary } = {}) {
   const widthOf = (text) => {
     if (!text) return 0;
     const w = measure?.(text);
@@ -161,7 +168,7 @@ export function editMenuGeometry(items, measure, scale = 1) {
   let widest = 0;
   for (const item of items) {
     const separator = isSeparator(item);
-    const shortcut = formatShortcut(item.shortcut);
+    const shortcut = formatShortcut(item.shortcut, { primary });
     const height = (separator ? SEPARATOR_HEIGHT : ROW_HEIGHT) * scale;
     rows.push({ ...item, separator, shortcut, y, height });
     y += height;

package/src/events.js

@@ -1705,6 +1705,11 @@ export class EventManager {
    *
    * `entry.handle(ev)` answers whether it took the key.
    *
+   * `entry.reserves(ev)`, optional, answers whether something *outside* the
+   * window is going to answer this key whatever we do — the macOS menu
+   * bar's key equivalents (`MenuBar`, delegated). Such a key is spent
+   * before any binding is offered it (`_runAccelerators`).
+   *
    * Registrations live on the **top-level** manager, which is the one thing
    * a `<popup>`, a nested `<window>` and the window itself all share — the
    * same grouping `_keyManager` resolves keys through. So a chord reaches
@@ -1740,11 +1745,30 @@ export class EventManager {
    * A menu that is *open* suppresses them by another route entirely: it
    * `preventDefault()`s the keys it is being driven with, one layer above
    * this (`components/Menu.js`).
+   *
+   * And a key one of them *reserves* reaches none of them. The Cocoa bridge
+   * shows us every key before `[NSApp sendEvent:]`, where the menu bar's
+   * key equivalent then runs its item regardless — so a binding here that
+   * answered ⌘S too would be a second command on one key, whichever of the
+   * two mounted last. Neither gate applies to that: the menu bar is not in
+   * the window, and a modal `<popup>` does not take keys from it.
    */
   _runAccelerators(ev) {
     const owner = this.topLevelManager;
     const entries = owner._accelerators;
     if (!entries?.size) return;
+    for (const entry of entries) {
+      let reserved = false;
+      try {
+        reserved = Boolean(entry.reserves?.(ev));
+      } catch (error) {
+        reportHandlerError(entry.anchor(), 'an accelerator', error);
+      }
+      if (reserved) {
+        ev.preventDefault();
+        return;
+      }
+    }
     const scopeRoot = owner._scopeRoot();
     const trapped = scopeRoot !== owner.node;
     for (const entry of [...entries].reverse()) {

package/src/frame/index.js

@@ -624,7 +624,7 @@ function PaneHostView({
         host.windowCursor?.(msg);
       } else if (msg?.type === 'pane-present') {
         host.setRect(node.abs);
-        host.present(msg.id);
+        host.present(msg.id, msg);
       } else if (msg?.type === 'pane-cursor') {
         // The pane names its cursor as an element that draws names one for
         // a point: this box is the node the host's pointer is over, so the

package/src/globalmenu.js

@@ -54,7 +54,7 @@
 // third-party menus consume dbusmenu. A second exporter is roughly double the
 // work for no consumer that the first one does not already reach.
 
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
 import { loadTransport, sessionBus } from './bus.js';
 import { desktopIntegrationEnabled } from './desktopintegration.js';
@@ -539,7 +539,20 @@ export function _resetGlobalMenuState() {
  * it. It is exported for a component that draws its own bar and wants the
  * same behaviour.
  */
-export function useGlobalMenu(
+export function useGlobalMenu(menus, options) {
+  return useGlobalMenuExport(menus, options).delegated;
+}
+
+/**
+ * `useGlobalMenu`, with the one more thing `MenuBar` needs to know about the
+ * delegate: which shortcuts it answers by itself. A panel answers none — it
+ * draws the rows, and the key is pressed in our window — but the macOS menu
+ * bar answers the ⌘ chords it holds as key equivalents, and a bar that
+ * matched them as well would run the item twice
+ * (`CocoaGlobalMenuExport.answersShortcut`). Read at key time, so it is
+ * whatever delegate is live then. Not public.
+ */
+export function useGlobalMenuExport(
   menus,
   { onSelect, onAboutToShow, enabled = true } = {},
 ) {
@@ -586,5 +599,10 @@ export function useGlobalMenu(
     exportRef.current?.update(menus ?? []);
   }, [menus]);
 
-  return enabled && exported;
+  const answersShortcut = useCallback(
+    (shortcut) => Boolean(exportRef.current?.answersShortcut?.(shortcut)),
+    [],
+  );
+
+  return { delegated: enabled && exported, answersShortcut };
 }

package/src/index.d.ts

@@ -290,7 +290,10 @@ 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).
+   * move without waiting). A `<Frame>` pane's frames of a new size are held
+   * to it as well: within it, the pane's last frame stays at its size while
+   * the next comes, and past it, it is stretched to the pane's new size, as
+   * every one is at 0.
    * `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

package/src/keysyms.d.ts

@@ -50,6 +50,36 @@ export function ctrlChordLetter(ev: {
   codepoint?: number | null;
 }): number | null;
 
+/** The modifier token a shortcut's primary means, in a menu `shortcut`'s
+ * vocabulary. */
+export type PrimaryModifier = 'Control' | 'Super';
+
+/**
+ * The modifier this app's shortcuts are pressed with: `'Super'` — ⌘ — where
+ * the backend says so (the Cocoa app does, as `app.primaryModifier`), and
+ * `'Control'` everywhere else. A backend fact, not a platform one: an X11
+ * app under XQuartz keeps Ctrl, like every other X client on that display.
+ */
+export function primaryModifier(
+  app?: { primaryModifier?: PrimaryModifier } | null,
+): PrimaryModifier;
+
+/**
+ * Is the primary modifier down for this event — ⌘ on the Cocoa backend, Ctrl
+ * everywhere else? What the built-in editors test before their
+ * Undo/Cut/Copy/Paste/Select All chords, so the keys the edit menu prints
+ * are the keys that do it.
+ *
+ * ```js
+ * if (primaryModifierHeld(ev, node.app) && ctrlChordLetter(ev) === keysymOf('d'))
+ *   duplicateLine();
+ * ```
+ */
+export function primaryModifierHeld(
+  ev: { ctrlKey?: boolean; metaKey?: boolean } | null | undefined,
+  app?: { primaryModifier?: PrimaryModifier } | null,
+): boolean;
+
 /**
  * The keysym an X11 key *name* stands for — `'Return'`, `'plus'`, `'F5'`,
  * `'s'` — or `undefined` for a name nothing here knows.

package/src/keysyms.js

@@ -247,6 +247,35 @@ export function ctrlChordLetter(ev) {
   return code >= 0x41 && code <= 0x5a ? code + 0x20 : code;
 }
 
+/**
+ * The modifier this app's shortcuts are pressed with: `'Super'` — ⌘ — where
+ * the backend says so (the Cocoa app does, as `app.primaryModifier`), and
+ * `'Control'` everywhere else.
+ *
+ * A backend fact, not a platform one: an X11 app under XQuartz keeps Ctrl,
+ * which is what every other X client on that display answers to.
+ */
+export function primaryModifier(app) {
+  return app?.primaryModifier === 'Super' ? 'Super' : 'Control';
+}
+
+/**
+ * Is the primary modifier down for this event — ⌘ on the Cocoa backend,
+ * Ctrl everywhere else? The test the built-in editors put in front of their
+ * Undo/Cut/Copy/Paste/Select All chords, so the keys the edit menu prints
+ * beside each row are the keys that do it.
+ *
+ * ```js
+ * if (primaryModifierHeld(ev, node.app) && ctrlChordLetter(ev) === keysymOf('d'))
+ *   duplicateLine();
+ * ```
+ */
+export function primaryModifierHeld(ev, app) {
+  return primaryModifier(app) === 'Super'
+    ? Boolean(ev?.metaKey)
+    : Boolean(ev?.ctrlKey);
+}
+
 /**
  * The X11 modifier mask bits, as they arrive on `ev.nativeEvent.buttons`
  * and as `fireEvent` takes them. Bit 3 (Mod1) is Alt and bit 6 (Mod4) is

package/src/menuitem.js

@@ -112,21 +112,62 @@ const KEY_LABELS = {
   Next: 'PgDn',
 };
 
+// The Mac prints a chord as glyphs, in one fixed order whatever order the
+// chord was written in — ⌃⌥⇧⌘ — and with nothing between them: `⇧⌘Z`, never
+// `Cmd+Shift+Z`. `Control` and `Super` are both ⌘ there, for the reason
+// `primaryModifier` gives below: a cross-platform chord is written in the
+// primary modifier, and the Mac's is Command.
+const MAC_MODIFIER_ORDER = ['Alt', 'Shift', 'Command'];
+const MAC_MODIFIER_GLYPHS = { Alt: '⌥', Shift: '⇧', Command: '⌘' };
+
+// The keys a Mac menu draws as a glyph rather than a word. The rest are
+// `KEY_LABELS`' answer, which is already the Mac's for punctuation.
+const MAC_KEY_LABELS = {
+  Return: '↩',
+  KP_Enter: '⌤',
+  Tab: '⇥',
+  BackSpace: '⌫',
+  Delete: '⌦',
+  Escape: '⎋',
+  Left: '←',
+  Right: '→',
+  Up: '↑',
+  Down: '↓',
+  Prior: '⇞',
+  Next: '⇟',
+  Home: '↖',
+  End: '↘',
+};
+
+const keyLabel = (key, labels) =>
+  labels[key] ??
+  KEY_LABELS[key] ??
+  (key.length === 1 ? key.toUpperCase() : key);
+
 /**
  * One `aas` alternative — `['Control', 'S']` — as the string a menu row
- * shows: `Ctrl+S`.
+ * shows: `Ctrl+S`, or `⌘S` where the primary modifier is ⌘.
  *
  * A single-character key is upper-cased because that is how every toolkit
  * prints one, and because dbusmenu carries the *key*, not the character it
  * types: `['Control', 's']` and `['Control', 'S']` are the same binding and
  * must not render differently.
  */
-function formatChord(chord) {
+function formatChord(chord, primary) {
   const { modifiers, key } = splitChord(chord);
-  const parts = [...modifiers].map((token) => MODIFIER_LABELS[token]);
-  if (key != null) {
-    parts.push(KEY_LABELS[key] ?? (key.length === 1 ? key.toUpperCase() : key));
+  if (primary === 'Super') {
+    const held = new Set(
+      [...modifiers].map((token) =>
+        token === 'Control' || token === 'Super' ? 'Command' : token,
+      ),
+    );
+    const glyphs = MAC_MODIFIER_ORDER.filter((token) => held.has(token))
+      .map((token) => MAC_MODIFIER_GLYPHS[token])
+      .join('');
+    return glyphs + (key == null ? '' : keyLabel(key, MAC_KEY_LABELS));
   }
+  const parts = [...modifiers].map((token) => MODIFIER_LABELS[token]);
+  if (key != null) parts.push(keyLabel(key, {}));
   return parts.join('+');
 }
 
@@ -137,11 +178,14 @@ function formatChord(chord) {
  * modifier tokens ending in the key. Only the first alternative is drawn —
  * a row has one shortcut column, and a menu that printed `Ctrl+S / F2` in it
  * would be wider than the menu for the benefit of the rarer binding.
+ *
+ * `primary` is the app's `primaryModifier` (keysyms.js): `'Super'` draws the
+ * chord the way a Mac menu does, `⇧⌘Z` for `['Control', 'Shift', 'Z']`.
  */
-export function formatShortcut(shortcut) {
+export function formatShortcut(shortcut, { primary = 'Control' } = {}) {
   const first = shortcut?.[0];
   if (!Array.isArray(first) || first.length === 0) return '';
-  return formatChord(first);
+  return formatChord(first, primary);
 }
 
 // What UI Events calls the modifiers, which is what `aria-keyshortcuts` is
@@ -160,19 +204,21 @@ const ARIA_MODIFIERS = {
  * dbusmenu's `aas` already has — so unlike the drawn menu, **every**
  * alternative is announced rather than only the first: a screen reader is
  * reading them out, not fitting them in a column.
+ *
+ * `primary` is `formatShortcut`'s: under `'Super'` a `Control` is ⌘, which
+ * UI Events calls `Meta`, so what is announced is what is drawn and bound.
  */
-export function ariaKeyShortcuts(shortcut) {
+export function ariaKeyShortcuts(shortcut, { primary = 'Control' } = {}) {
   if (!isValidShortcut(shortcut)) return undefined;
+  const name = (token) => {
+    if (!MODIFIER_TOKENS.has(token)) return KEY_LABELS[token] ?? token;
+    return primary === 'Super' && token === 'Control'
+      ? 'Meta'
+      : ARIA_MODIFIERS[token];
+  };
+  // a chord naming both `Control` and `Super` is one ⌘ there, said once
   return shortcut
-    .map((chord) =>
-      chord
-        .map((token) =>
-          MODIFIER_TOKENS.has(token)
-            ? ARIA_MODIFIERS[token]
-            : (KEY_LABELS[token] ?? token),
-        )
-        .join('+'),
-    )
+    .map((chord) => [...new Set(chord.map(name))].join('+'))
     .join(' ');
 }
 

package/src/node.d.ts

@@ -73,6 +73,29 @@ export interface Context2D {
    * `'globalCompositeOperation' in ctx`.
    */
   globalCompositeOperation?: string;
+  /**
+   * Canvas's: whether an image drawn scaled or turned is smoothed, or
+   * drawn as its nearest pixels. Native contexts only (macOS, Windows), and
+   * only where the bridge can set it: assign and read back to know.
+   */
+  imageSmoothingEnabled?: boolean;
+  /**
+   * Canvas's: how it is smoothed, `'low'` being bilinear. A native context
+   * starts at `'medium'`, which on macOS resamples the whole source for a
+   * draw through a matrix whatever the clip — so a surface drawn a tile at
+   * a time is far cheaper at `'low'`.
+   */
+  imageSmoothingQuality?: 'low' | 'medium' | 'high';
+  /**
+   * Canvas's: a CSS filter list applied to what is drawn after it. Native
+   * contexts only (macOS, Windows), and only the colour functions —
+   * `grayscale()`, `sepia()`, `saturate()`, `hue-rotate()`, `invert()`,
+   * `brightness()`, `contrast()` and `opacity()` — over a bridge that reads
+   * a surface's pixels back. Anything else does not stick: assign and read
+   * back to know. Absent on X11, whose server runs no colour matrix and
+   * answers a read a round trip later.
+   */
+  filter?: string;
   save(): void;
   restore(): void;
   translate(x: number, y: number): void;

package/src/nodes/editmenupopup.js

@@ -5,6 +5,7 @@
 import { deviceAnchorArea, windowOrigin } from '../anchor.js';
 import { armPasteState, canPaste } from '../pastestate.js';
 import {
+  primaryModifier,
   XK_RETURN,
   XK_KP_ENTER,
   XK_UP,
@@ -125,6 +126,7 @@ export function openEditMenu(node, at, actions = {}) {
     items,
     (text) => app?.fonts?.layout(text, style)?.width,
     s,
+    { primary: primaryModifier(app) },
   );
   const deviceAt = at && {
     ...at,
@@ -221,6 +223,17 @@ export function openEditMenu(node, at, actions = {}) {
   node._editMenu = popup;
   // read *before* the menu takes the keyboard, and handed back on close
   node._editMenuRestore = node._focusManager()?.focused ?? null;
+  // The window losing focus closes it — the user went to another
+  // application, ⌘-Tab or a click on its window. Neither reaches us as a
+  // press: the grab redirects presses only between windows of ours on Cocoa,
+  // and a popup panel never takes the keyboard there, so this is the one
+  // event that says so. The node keeps its focus across the blur, so nothing
+  // in the tree hears it either; the same answer `Menu` and `Select` give
+  // (`useDismissOnWindowBlur`, components/anchor.js).
+  node._editMenuOffBlur =
+    node.root?.onWindowFocusChange?.((focused) => {
+      if (!focused) closeEditMenu(node);
+    }) ?? null;
   // the menu takes the keyboard so arrows and Escape reach it rather than
   // the element behind it
   popup.events?.focus?.(canvas);
@@ -241,6 +254,8 @@ export function closeEditMenu(node) {
   const popup = node?._editMenu;
   if (!popup) return;
   node._editMenu = null;
+  node._editMenuOffBlur?.();
+  node._editMenuOffBlur = null;
   const restore = node._editMenuRestore;
   node._editMenuRestore = null;
   // the popup is a child, so a node destroyed while its menu was up took the
@@ -255,6 +270,10 @@ export function closeEditMenu(node) {
   // menu and a ring appearing on the way back would be news to nobody. A
   // surface that was not focusable in the first place, or that stopped being
   // on screen while the menu was up, gets nothing back rather than the
-  // destroyed menu canvas keeping the keyboard.
-  events.focus(events._canRestoreTo(restore) ? restore : null, 'pointer');
+  // destroyed menu canvas keeping the keyboard. And a restore, which takes
+  // the window no keyboard: a menu closed because the user went to another
+  // application must not drag them back to this one.
+  events.focus(events._canRestoreTo(restore) ? restore : null, 'pointer', {
+    restoring: true,
+  });
 }

package/src/nodes/textarea.js

@@ -10,6 +10,7 @@ import {
   XK_PAGE_UP,
   XK_PAGE_DOWN,
   XK_END,
+  primaryModifierHeld,
 } from '../keysyms.js';
 import {
   scrollbarGeometry,
@@ -235,7 +236,8 @@ export class TextAreaNode extends TextInputNode {
     const layout = this._valueLayout();
 
     if (k === XK_RETURN || k === XK_KP_ENTER) {
-      if (ev.ctrlKey) {
+      // Ctrl+Enter, ⌘↩ on the Cocoa backend
+      if (primaryModifierHeld(ev, this.app)) {
         this._fireValueEvent('onSubmit', this.value, ev.nativeEvent);
         return true;
       }

package/src/nodes/textinput.js

@@ -14,6 +14,7 @@ import { lastInputTime } from '../inputtime.js';
 import {
   ctrlChordLetter,
   MOD,
+  primaryModifierHeld,
   XK_BACKSPACE,
   XK_RETURN,
   XK_KP_ENTER,
@@ -550,7 +551,9 @@ export class TextInputNode extends Node {
       this._moveCaret(this._chars().length, ev.shiftKey);
       return true;
     }
-    if (ev.ctrlKey) {
+    // Ctrl, or ⌘ on the Cocoa backend (`primaryModifierHeld`): the keys the
+    // edit menu prints beside its rows are the keys that do what they say
+    if (primaryModifierHeld(ev, this.app)) {
       const letter = ctrlChordLetter(ev);
       if (letter === 0x61 /* a */) {
         this._selectAll();
@@ -562,10 +565,12 @@ export class TextInputNode extends Node {
       } else if (letter === 0x76 /* v */) {
         this._pasteFrom();
       } else if (letter === 0x7a /* z */) {
-        // Ctrl+Shift+Z redoes, the way it does in GTK and Qt
+        // Ctrl+Shift+Z redoes, the way it does in GTK and Qt — and ⇧⌘Z is
+        // the Mac's own redo
         if (ev.shiftKey) this.redo();
         else this.undo();
-      } else if (letter === 0x79 /* y */) {
+      } else if (letter === 0x79 /* y */ && !ev.metaKey) {
+        // Ctrl+Y is Windows' redo; ⌘Y is nobody's, so it is not taken
         this.redo();
       } else {
         // A chord this field has no answer for is not the field's: Ctrl+S
@@ -576,6 +581,11 @@ export class TextInputNode extends Node {
       }
       return true;
     }
+    // …and a chord on the other one is not text either. AppKit hands over
+    // the key's bare character with ⌘ or ⌃ held, so ⌘S in a focused field
+    // typed an `s` before this, and ⌃A typed an `a` once ⌘ became the
+    // primary — Ctrl and Super chords are commands on every backend.
+    if (ev.ctrlKey || ev.metaKey) return false;
     if (ev.codepoint != null && ev.codepoint >= 0x20 && ev.codepoint !== 0x7f) {
       const ch = String.fromCodePoint(ev.codepoint);
       this._insert(ch, 'type');

package/src/textselection.js

@@ -30,7 +30,7 @@
 
 import { callHandler } from './errors.js';
 import { lastInputTime } from './inputtime.js';
-import { ctrlChordLetter } from './keysyms.js';
+import { ctrlChordLetter, primaryModifierHeld } from './keysyms.js';
 import { codePoints, wordRangeAt } from './textrange.js';
 // --- who is showing a selection ------------------------------------------
 //
@@ -201,14 +201,14 @@ export class TextSelection {
   }
 
   /**
-   * Ctrl+A and Ctrl+C, run as this element's default action — which is why a
-   * surface is a focus target (a11y.js): the copy has to have somewhere to
-   * arrive. Nothing else is bound. A read-only document has no caret, so
-   * shift+arrows would be caret browsing, which is a mode rather than a
-   * default.
+   * Ctrl+A and Ctrl+C — ⌘A and ⌘C on the Cocoa backend — run as this
+   * element's default action, which is why a surface is a focus target
+   * (a11y.js): the copy has to have somewhere to arrive. Nothing else is
+   * bound. A read-only document has no caret, so shift+arrows would be caret
+   * browsing, which is a mode rather than a default.
    */
   keyDown(ev) {
-    if (!ev.ctrlKey) return;
+    if (!primaryModifierHeld(ev, this.node.app)) return;
     const letter = ctrlChordLetter(ev);
     if (letter === 0x61 /* a */) {
       this.selectAll();

package/src/types/components.d.ts

@@ -579,6 +579,10 @@ export interface MenuItem {
    * the menu is mounted, without the menu being opened (#351). `enabled`
    * and `visible` gate the binding with the row. `accelerators={false}` on
    * the menu turns that off for an app with a dispatcher of its own.
+   *
+   * `Control` is the primary modifier: on the Cocoa backend `[['Control',
+   * 'S']]` is drawn `⌘S`, bound to ⌘S, and installed in the macOS menu bar
+   * as ⌘S — which then answers it by itself (docs/events.md).
    */
   shortcut?: MenuShortcut;
   /** With `toggleState`, draws a check mark or a radio dot in the gutter. */
@@ -654,8 +658,10 @@ export interface MenuBarProps extends WidgetProps {
   /**
    * Honour the items' own `shortcut`s while this bar is mounted — including
    * when the desktop's panel has taken the menu over, since the panel draws
-   * the rows but the key is pressed in this window. On by default; `false`
-   * leaves the chords to an app that dispatches its own.
+   * the rows but the key is pressed in this window. The macOS menu bar is the
+   * exception: it answers the ⌘ chords it holds as key equivalents itself,
+   * and the window leaves those alone. On by default; `false` leaves the
+   * chords to an app that dispatches its own.
    */
   accelerators?: boolean;
   fontSize?: number;

package/src/types/elements.d.ts

@@ -739,7 +739,7 @@ export interface TextInputProps extends DrawnProps<TextInputNode> {
    * both read naturally.
    */
   onChange?: (ev: ChangeEvent<TextInputNode>) => void;
-  /** Enter — or Ctrl+Enter in a `<textarea>`. */
+  /** Enter — or Ctrl+Enter in a `<textarea>` (⌘↩ on the Cocoa backend). */
   onSubmit?: (ev: SubmitEvent<TextInputNode>) => void;
   placeholder?: string;
   placeholderColor?: Color;

package/src/types/events.d.ts

@@ -7,6 +7,7 @@
 import type { RefObject } from 'react';
 import type { DrawnNode, NtkWindow, TextInputNode } from './nodes.js';
 import type { MenuShortcut } from './components.js';
+import type { PrimaryModifier } from '../keysyms.js';
 
 /** The raw ntk/X11 event a synthetic one was made from. */
 export interface NativeEvent {
@@ -331,7 +332,7 @@ export interface ChangeEvent<T = TextInputNode> extends Omit<
 }
 
 /**
- * `<textinput onSubmit>` — Enter, or Ctrl+Enter in a `<textarea>`. Same
+ * `<textinput onSubmit>` — Enter, or Ctrl+Enter in a `<textarea>` (⌘↩ on Cocoa). Same
  * shape as {@link ChangeEvent}; `nativeEvent` is the X key event.
  */
 export interface SubmitEvent<T = TextInputNode> extends Omit<
@@ -556,7 +557,8 @@ export interface AcceleratorOptions {
  * Exact on Control/Alt/Shift/Super, indifferent to Caps Lock and Num Lock,
  * 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.
+ * `Control` is the app's primary modifier: ⌘ on the Cocoa backend, the key
+ * its menus print. 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 —
@@ -569,10 +571,25 @@ export function useAccelerator(
   options?: AcceleratorOptions,
 ): void;
 
+export interface MatchesShortcutOptions {
+  /**
+   * The app's primary modifier — `primaryModifier(app)` from
+   * `react-x11/keysyms`. `'Super'` reads a chord's `Control` (and its
+   * `Super`) as ⌘ and wants ⌃ up, which is the Cocoa backend's rule;
+   * `'Control'`, the default, reads the chord literally.
+   */
+  primary?: PrimaryModifier;
+}
+
 /**
  * Whether a key event presses any alternative of a `shortcut` — the matcher
  * the menus and {@link useAccelerator} both run on, for an application
- * dispatching chords its own way.
+ * dispatching chords its own way. Pass the app's primary modifier to match
+ * the way they do:
+ *
+ * ```ts
+ * matchesShortcut(ev, [['Control', 'S']], { primary: primaryModifier(app) });
+ * ```
  */
 export function matchesShortcut(
   ev: {
@@ -584,4 +601,5 @@ export function matchesShortcut(
     metaKey?: boolean;
   },
   shortcut: MenuShortcut | undefined,
+  options?: MatchesShortcutOptions,
 ): boolean;