react-x11 2.38.0 → 2.40.0

package/src/cocoa/sprites.js

@@ -27,7 +27,10 @@
 // `@windowkit/appkit` 0.19 (`transformForms()`) along with the negative
 // delay a part joined half way through needs, so that is the bridge sprites
 // ask for: on an older one nothing is asked and every part is drawn by its
-// element.
+// element. Or it is CSS's `matrix3d()`, a part turned out of the plane and
+// seen in a perspective, which Core Animation draws through the whole
+// matrix on the GPU: a part none of whose corners is behind the viewer, on a
+// bridge that takes one (`matrix3d`).
 //
 // A part none of which shows — scrolled out of its pane, or outside its own
 // clip — keeps its layer, cut to show nothing, up to a budget of raster for
@@ -68,6 +71,14 @@ const AFTER_CHILDREN = Number.MAX_SAFE_INTEGER;
 
 const IDENTITY = Object.freeze([1, 0, 0, 1, 0, 0]);
 
+// what a part with no bounds may reach (`_underDrawn`)
+const EVERYWHERE = Object.freeze({
+  x: -1e9,
+  y: -1e9,
+  width: 2e9,
+  height: 2e9,
+});
+
 const ORIGIN = Object.freeze({ x: 0, y: 0 });
 
 // what a part with no part lifted inside it is handed
@@ -98,7 +109,20 @@ const isRect = (r) =>
   r.width > 0 &&
   r.height > 0;
 
-const isMatrix = (m) => Array.isArray(m) && m.length === 6 && m.every(finite);
+// CSS's `matrix(a, b, c, d, e, f)`, or its `matrix3d()`'s sixteen numbers
+const isMatrix = (m) =>
+  Array.isArray(m) && (m.length === 6 || m.length === 16) && m.every(finite);
+
+const isSolid = (m) => m.length === 16;
+
+/** Does `sprite` turn out of the plane, at rest or in an animation? */
+function solidSprite(sprite) {
+  if (sprite.transform && isSolid(sprite.transform)) return true;
+  for (const a of sprite.animations ?? []) {
+    if (a.property === 'transform' && a.values.some(isSolid)) return true;
+  }
+  return false;
+}
 
 const isCurve = (t) =>
   typeof t === 'string' ||
@@ -203,12 +227,15 @@ const originOf = (sprite) =>
     y: sprite.rect.y + sprite.rect.height / 2,
   };
 
-/** `rect` through `m` about `origin`: the bounds of its four corners. */
+/** `rect` through `m` about `origin`: the bounds of its four corners, or
+ *  null where `m` is a matrix3d that puts a corner behind the viewer, past
+ *  which the plane's picture has no bounds. */
 function mapRect(rect, m, origin) {
   let x0 = Infinity;
   let y0 = Infinity;
   let x1 = -Infinity;
   let y1 = -Infinity;
+  const solid = isSolid(m);
   for (const [px, py] of [
     [rect.x, rect.y],
     [rect.x + rect.width, rect.y],
@@ -217,8 +244,18 @@ function mapRect(rect, m, origin) {
   ]) {
     const dx = px - origin.x;
     const dy = py - origin.y;
-    const x = m[0] * dx + m[2] * dy + m[4] + origin.x;
-    const y = m[1] * dx + m[3] * dy + m[5] + origin.y;
+    let x;
+    let y;
+    if (solid) {
+      // column-major, as `matrix3d()` writes it: the point (dx, dy, 0, 1)
+      const w = m[3] * dx + m[7] * dy + m[15];
+      if (!(w > W_NEAR)) return null;
+      x = (m[0] * dx + m[4] * dy + m[12]) / w + origin.x;
+      y = (m[1] * dx + m[5] * dy + m[13]) / w + origin.y;
+    } else {
+      x = m[0] * dx + m[2] * dy + m[4] + origin.x;
+      y = m[1] * dx + m[3] * dy + m[5] + origin.y;
+    }
     if (x < x0) x0 = x;
     if (y < y0) y0 = y;
     if (x > x1) x1 = x;
@@ -227,6 +264,10 @@ function mapRect(rect, m, origin) {
   return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
 }
 
+// A corner whose w is this close to the viewer's plane is as good as behind
+// it: projected that near, it lands off any window.
+const W_NEAR = 1e-6;
+
 function unionRect(a, b) {
   if (!a) return b;
   const x = Math.min(a.x, b.x);
@@ -242,7 +283,8 @@ function unionRect(a, b) {
 /**
  * Everywhere `sprite` can draw while its animations run: its reach through
  * its own transform and every transform it is animated through, out to
- * whole pixels and the antialiasing a raster is padded for. Between two
+ * whole pixels and the antialiasing a raster is padded for — or null, where
+ * one of those puts a corner of it behind the viewer. Between two
  * keyframes Core Animation interpolates the matrices by their parts, which
  * stays within a pixel of the two for the densely sampled keyframes a CSS
  * transform arrives as; an element whose keyframes are far apart, or whose
@@ -271,12 +313,18 @@ function extentOf(sprite) {
   if (about?.key !== key) {
     let box = mapRect(rel, m0, ORIGIN);
     for (const a of sprite.animations ?? []) {
-      if (a.property !== 'transform') continue;
-      for (const m of a.values) box = unionRect(box, mapRect(rel, m, ORIGIN));
+      if (a.property !== 'transform' || !box) continue;
+      for (const m of a.values) {
+        const at = mapRect(rel, m, ORIGIN);
+        box = at && unionRect(box, at);
+        if (!box) break;
+      }
     }
     about = { key, box };
     if (turns) EXTENTS.set(turns, about);
   }
+  // a corner behind the viewer, at rest or on the way: nowhere bounded
+  if (!about.box) return null;
   const box = {
     x: about.box.x + origin.x,
     y: about.box.y + origin.y,
@@ -311,7 +359,31 @@ function rasterRectOf(sprite) {
 }
 
 const sameMatrix = (a, b) =>
-  a === b || (a != null && b != null && a.every((v, i) => v === b[i]));
+  a === b ||
+  (a != null &&
+    b != null &&
+    a.length === b.length &&
+    a.every((v, i) => v === b[i]));
+
+/**
+ * A part's matrix in device pixels as the bridge takes it, in points: its
+ * translation over the scale and, for a matrix3d, its perspective row times
+ * it — S⁻¹·M·S, with S scaling x, y and z, so that a turn and a perspective
+ * of so many CSS pixels look the same at any scale.
+ */
+function inPoints(m, s) {
+  if (!isSolid(m)) {
+    return { matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s] };
+  }
+  const p = m.slice();
+  p[12] /= s;
+  p[13] /= s;
+  p[14] /= s;
+  p[3] *= s;
+  p[7] *= s;
+  p[11] *= s;
+  return { matrix3d: p };
+}
 
 /**
  * The lifted parts of every element in one window: a layer each, its raster,
@@ -326,9 +398,10 @@ export class SpriteLayers {
     this.app = promotion.app;
     // a matrix and a negative delay are what a CSS animation needs from the
     // bridge, and @windowkit/appkit 0.19 is where both are
-    this.supported = Boolean(
-      this.native.transformForms?.()?.includes?.('matrix'),
-    );
+    const forms = this.native.transformForms?.();
+    this.supported = Boolean(forms?.includes?.('matrix'));
+    // and a part turned out of the plane, its matrix3d, the same release
+    this.solid = Boolean(forms?.includes?.('matrix3d'));
     // and a video's frames on a layer need its video surfaces
     this.videos = canLiftVideo(this.native);
     this.hosts = new Map(); // element -> Map(key -> state)
@@ -429,7 +502,12 @@ export class SpriteLayers {
           radius: sprite.clip ? (sprite.clipRadius ?? 0) : 0,
           bounds: null,
         };
+        // turned out of the plane, on a bridge that takes no matrix3d
+        if (!this.solid && solidSprite(sprite)) continue;
         const extent = extentOf(sprite);
+        // a corner behind the viewer: the element draws it, which it can cut
+        // where the plane meets the viewer's
+        if (!extent) continue;
         const bounds = cut.clip ? intersectRects(extent, cut.clip) : extent;
         if (parent) {
           // the parent was asked about everywhere it can be, and its layer
@@ -544,8 +622,9 @@ export class SpriteLayers {
         drawn.push(state.extent);
         continue;
       }
-      // the element draws it, where its own clip lets it show
-      const extent = extentOf(sprite);
+      // the element draws it, where its own clip lets it show — anywhere,
+      // for one with a corner behind the viewer and no clip
+      const extent = extentOf(sprite) ?? EVERYWHERE;
       const shows = sprite.clip ? intersectRects(extent, sprite.clip) : extent;
       if (shows) drawn.push(shows);
     }
@@ -776,7 +855,7 @@ export class SpriteLayers {
       }
     }
     if (!sameMatrix(prev.matrix, m)) {
-      out.transform = { matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s] };
+      out.transform = inPoints(m, s);
       any = true;
     }
     if (any) this.native.setLayerProps(state.layer, out);
@@ -843,9 +922,7 @@ export class SpriteLayers {
       const opts = {
         values:
           a.property === 'transform'
-            ? a.values.map((m) => ({
-                matrix: [m[0], m[1], m[2], m[3], m[4] / s, m[5] / s],
-              }))
+            ? a.values.map((m) => inPoints(m, s))
             : a.values,
         duration: a.duration / 1000,
         id: caId,

package/src/components/Menu.js

@@ -24,9 +24,11 @@ import {
   useDismissOnWindowBlur,
 } from './anchor.js';
 import { typeAheadChar, useTypeAhead } from './typeahead.js';
-import { useGlobalMenu } from '../globalmenu.js';
+import { useGlobalMenuExport } from '../globalmenu.js';
 import { acceleratedItem } from '../accelerators.js';
 import { useAcceleratorEntry } from '../acceleratorhooks.js';
+import { useAppOrNull } from '../appcontext.js';
+import { primaryModifier } from '../keysyms.js';
 import { useTopLevelWindow } from '../windowid.js';
 import { MENU_TEXT_WEIGHT } from '../faces.js';
 import {
@@ -121,12 +123,17 @@ function menuMetrics(theme, native, fontSize) {
   };
 }
 
+// `primary` rides along with the sizes because it is one too: the shortcut
+// column is measured from the same string the row then draws — `⌘S` on the
+// Cocoa backend, `Ctrl+S` elsewhere — and the binding matches the key that
+// string names (`useMenuAccelerators`).
 function useMenuMetrics(fontSize) {
   const theme = useTheme();
   const native = useNativeControls();
+  const primary = primaryModifier(useAppOrNull());
   return useMemo(
-    () => menuMetrics(theme, native, fontSize),
-    [theme, native, fontSize],
+    () => ({ ...menuMetrics(theme, native, fontSize), primary }),
+    [theme, native, fontSize, primary],
   );
 }
 
@@ -272,7 +279,9 @@ function menuListWidth(node, items, metrics) {
       size: metrics.fontSize,
       weight: metrics.weight,
     }).width;
-    const accelerator = formatShortcut(item.shortcut);
+    const accelerator = formatShortcut(item.shortcut, {
+      primary: metrics.primary,
+    });
     const shortcut = accelerator
       ? measureLabel(node, accelerator, {
           size: metrics.fontSize,
@@ -471,7 +480,9 @@ function MenuRow({
   }
   const dim = !isEnabled(item);
   const submenu = hasSubmenu(item);
-  const accelerator = formatShortcut(item.shortcut);
+  const accelerator = formatShortcut(item.shortcut, {
+    primary: metrics.primary,
+  });
   const rowInk = dim ? theme.textMuted : active ? theme.hoverText : theme.text;
   if (process.env.NODE_ENV !== 'production') checkShortcut(item);
   return h(
@@ -489,7 +500,9 @@ function MenuRow({
       // the label alone: without it, name-from-contents would read the
       // shortcut and the submenu arrow into the name ("New Ctrl+N")
       'aria-label': typeof item.label === 'string' ? item.label : undefined,
-      'aria-keyshortcuts': ariaKeyShortcuts(item.shortcut),
+      'aria-keyshortcuts': ariaKeyShortcuts(item.shortcut, {
+        primary: metrics.primary,
+      }),
       'aria-checked': item.toggleType
         ? ariaChecked(item.toggleState)
         : undefined,
@@ -922,17 +935,40 @@ function handleMenuKey(
  * `anchorRef` is what the binding hangs off — the bar, or the window when
  * there is no bar to hang off — and decides what a modal `<popup>` takes it
  * away from (`EventManager._runAccelerators`).
+ *
+ * `primary` is the app's primary modifier, so a chord's `Control` is ⌘ on
+ * the Cocoa backend — the key the row prints, and the key the macOS menu
+ * bar installs. Which is where the one exception comes from:
+ * `answeredElsewhere(shortcut)` names the chords a delegate fires the item
+ * for by itself. The bridge hands JS every key *before* AppKit dispatches
+ * it, so ⌘S reaches the window's bindings and then the menu bar's key
+ * equivalent; selecting here too would save twice. So such a chord is
+ * *reserved*: spent before any binding in the window is offered it, this
+ * one included, and left to the menu bar — a `useAccelerator` on ⌘S
+ * mounted after the bar would otherwise be the same double run by another
+ * route. A chord the menu bar cannot spell (F5, a second alternative,
+ * `plus`) is not one, and stays this binding's.
  */
-function useMenuAccelerators(items, select, anchorRef, enabled) {
+function useMenuAccelerators(
+  items,
+  select,
+  anchorRef,
+  { enabled, primary, answeredElsewhere },
+) {
   useAcceleratorEntry(
     anchorRef,
     (ev) => {
-      const item = acceleratedItem(items, ev);
+      const item = acceleratedItem(items, ev, { primary });
       if (!item) return false;
       select(item);
       return true;
     },
     enabled,
+    answeredElsewhere &&
+      ((ev) => {
+        const item = acceleratedItem(items, ev, { primary });
+        return Boolean(item && answeredElsewhere(item.shortcut));
+      }),
   );
 }
 
@@ -970,7 +1006,10 @@ export function ContextMenu({
     onSelect?.(item);
   };
 
-  useMenuAccelerators(items, select, ref, accelerators);
+  useMenuAccelerators(items, select, ref, {
+    enabled: accelerators,
+    primary: metrics.primary,
+  });
 
   // the wrapper keeps the focus the right-click gave it, so `onBlur` below
   // never fires when the *window* loses focus — and the menu is holding a
@@ -1101,7 +1140,10 @@ export function MenuBar({
   // `visible` as a property, so hiding one there is a patch the panel applies
   // rather than a structural change that renumbers everything after it.
   const bar = useMemo(() => visibleItems(menus), [menus]);
-  const delegated = useGlobalMenu(menus, { onSelect, enabled: globalMenu });
+  const { delegated, answersShortcut } = useGlobalMenuExport(menus, {
+    onSelect,
+    enabled: globalMenu,
+  });
 
   // What the bar turned out to be, which is the one thing here that cannot
   // be worked out in a render: layout runs on the frame clock, after the
@@ -1263,7 +1305,11 @@ export function MenuBar({
     }),
     [owner],
   );
-  useMenuAccelerators(menus, select, acceleratorAnchor, accelerators);
+  useMenuAccelerators(menus, select, acceleratorAnchor, {
+    enabled: accelerators,
+    primary: metrics.primary,
+    answeredElsewhere: delegated ? answersShortcut : null,
+  });
 
   const moveMenu = (dir) => {
     if (!entries.length) return;

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