react-x11 2.6.1 → 2.7.0

package/src/components/Radio.js

@@ -5,7 +5,14 @@
 import React, { useContext, useEffect, useMemo, useRef } from 'react';
 import { useAppOrNull } from '../appcontext.js';
 import { changeEvent } from './change.js';
-import { Bezel, bezelNatural, useNativeControls } from './native.js';
+import {
+  Bezel,
+  CONTROL_FONT_SIZE,
+  NO_ROW_RING,
+  bezelNatural,
+  nativeRingStyle,
+  useNativeControls,
+} from './native.js';
 import { focusRingStyle, labelContent, useControl, useTheme } from './theme.js';
 import { XK_DOWN, XK_LEFT, XK_RIGHT, XK_UP } from './keys.js';
 
@@ -67,6 +74,7 @@ export function Radio({ value, children, label, disabled = false, native }) {
   const {
     hover,
     focused,
+    focusVisible,
     pressed,
     props,
     style: controlStyle,
@@ -97,6 +105,7 @@ export function Radio({ value, children, label, disabled = false, native }) {
         style: [
           controlStyle,
           { flexDirection: 'row', alignItems: 'center', gap: 8 },
+          NO_ROW_RING,
         ],
       },
       h(Bezel, {
@@ -107,11 +116,17 @@ export function Radio({ value, children, label, disabled = false, native }) {
         style: {
           width: nat.width,
           height: nat.height,
-          ...focusRingStyle(theme, focused),
+          // a circle: the ring rounds with it
+          ...nativeRingStyle(theme, focusVisible, nat.height / 2),
         },
       }),
+      // At the control font size, as the cell's own title is: the bezel is
+      // designed beside 13pt, and the palette's 14px read a size too large
+      // next to it. Centred on the box, which is where AppKit centres it
+      // (measured: within a quarter point).
       labelContent(children ?? label, {
         color: disabled ? theme.textMuted : theme.text,
+        fontSize: CONTROL_FONT_SIZE.regular,
       }),
     );
   }

package/src/components/Select.js

@@ -9,7 +9,12 @@ import { Icon } from './Icon.js';
 import {
   ABS_FILL,
   Bezel,
+  NATIVE_MENU,
+  NATIVE_RING,
+  TITLE_BASELINE,
   bezelNatural,
+  bezelShadow,
+  nativeTitleStyle,
   pressWash,
   useNativeControls,
 } from './native.js';
@@ -52,6 +57,51 @@ const ITEM_PAD_RIGHT = ITEM_PAD;
 // sized against 14 under a theme that set 18 is a row its own label does not
 // fit in.
 const itemHeight = (fontSize) => capBand(fontSize) + ITEM_PAD * 2;
+
+/**
+ * The menu's geometry: the palette's, or — where the trigger is a native
+ * popup bezel — NSMenu's, so the sheet that drops from it is the one the
+ * bezel promises. The drawn menu marks the chosen option in bold; a native
+ * popup's menu marks it with a check in the column every row reserves, at
+ * regular weight, as the bezel's own menu does.
+ */
+function menuMetrics(theme, native) {
+  if (native) {
+    const padLeft = NATIVE_MENU.padLeft + NATIVE_MENU.markColumn;
+    const cap = capBand(NATIVE_MENU.fontSize);
+    return {
+      ...NATIVE_MENU,
+      padLeft,
+      selectedWeight: 'normal',
+      check: true,
+      // Where a row's capitals end, from the row's top: the centred band,
+      // at the whole pixel. Placed there by the row rather than centred by
+      // layout — centring puts the band at 6.5pt, which floors to 6 at 1×
+      // and is exact at 2×, and the menu that opens over the trigger is
+      // aligned on this number, so it has to be the same one at every
+      // scale.
+      capsBottom: Math.floor((NATIVE_MENU.row - cap) / 2) + cap,
+      // How far the menu hangs past the trigger: left, so the titles line
+      // up (the menu's inset less the trigger's); right, past the arrow
+      // capsule, read off the screen at 10pt.
+      hang: {
+        left: MENU_BORDER + NATIVE_MENU.pad + padLeft - TRIGGER_PAD_LEFT,
+        right: 10,
+      },
+    };
+  }
+  return {
+    fontSize: theme.fontSize,
+    weight: 'normal',
+    selectedWeight: 'bold',
+    check: false,
+    row: itemHeight(theme.fontSize),
+    pad: MENU_PAD,
+    padLeft: ITEM_PAD_LEFT,
+    padRight: ITEM_PAD_RIGHT,
+    radius: rowRadius(theme, MENU_BORDER, MENU_PAD),
+  };
+}
 // The scrolling pane's own padding, and so the inset between the edge
 // and an option — which is what makes the highlight read as a pill on the
 // menu rather than a band across it, and what the pill's own corner radius
@@ -63,6 +113,10 @@ const MENU_PAD = 4;
 // where it meets the desktop behind it, and a theme that draws 2px borders
 // on its *controls* does not mean a 2px outline around every popup.
 const MENU_BORDER = 1;
+// Where a native popup bezel's title starts, from the trigger's left edge —
+// and so what the menu's own inset is measured against when it opens over
+// the trigger (`menuAnchorOptions`).
+const TRIGGER_PAD_LEFT = 10;
 // the scrollbar is drawn *over* the content rather than insetting it
 // (`nodes.js`, SCROLLBAR_WIDTH), so a menu that scrolls reserves the room
 const SCROLLBAR_WIDTH = 6;
@@ -88,23 +142,28 @@ function normalizeOption(option) {
  * than the screen it has to open on — `anchorRect` can slide a popup left to
  * fit, but nothing can rescue one that is wider than the display.
  */
-function menuWidth(node, options, value, scrolls, fontSize) {
+function menuWidth(node, options, value, scrolls, metrics) {
   let widest = 0;
   for (const option of options) {
     const { width } = measureLabel(node, option.label, {
-      size: fontSize,
-      weight: option.value === value ? 'bold' : 'normal',
+      size: metrics.fontSize,
+      weight: option.value === value ? metrics.selectedWeight : 'normal',
     });
     if (width > widest) widest = width;
   }
   const chrome =
-    (MENU_BORDER + MENU_PAD) * 2 +
-    ITEM_PAD_LEFT +
-    ITEM_PAD_RIGHT +
+    (MENU_BORDER + metrics.pad) * 2 +
+    metrics.padLeft +
+    metrics.padRight +
     (scrolls ? SCROLLBAR_WIDTH : 0);
   // logical throughout: the trigger's rect divided out of device pixels,
   // the measured labels already logical (measureLabel), the area logical
-  const trigger = node.abs.width / node.scale;
+  // A native popup's menu opens over its control and covers all of it,
+  // the arrow capsule included — it hangs out on both sides (`hang`).
+  const trigger =
+    node.abs.width / node.scale +
+    (metrics.hang?.left ?? 0) +
+    (metrics.hang?.right ?? 0);
   const width = Math.max(trigger, Math.ceil(widest) + chrome);
   const area = anchorArea(node);
   return area ? Math.min(width, area.width) : width;
@@ -119,6 +178,7 @@ function Option({
   nodeRef,
   posinset,
   setsize,
+  metrics,
 }) {
   const theme = useTheme();
   // one highlight, shared by pointer and keyboard: hovering moves the
@@ -135,20 +195,34 @@ function Option({
       onMouseEnter: () => onHover?.(),
       onClick: () => onPick(option),
       style: {
-        height: itemHeight(theme.fontSize),
-        justifyContent: 'center',
-        paddingLeft: ITEM_PAD_LEFT,
-        paddingRight: ITEM_PAD_RIGHT,
+        height: metrics.row,
+        justifyContent: metrics.capsBottom ? 'flex-end' : 'center',
+        paddingBottom: metrics.capsBottom
+          ? metrics.row - metrics.capsBottom
+          : 0,
+        paddingLeft: metrics.padLeft,
+        paddingRight: metrics.padRight,
         // the menus' pill, for the same reason and by the same rule: an
         // option list and a menu are one surface with rows in it, and two
         // shapes for that would only say the widgets were written apart
-        borderRadius: rowRadius(theme, MENU_BORDER, MENU_PAD),
+        borderRadius: metrics.radius,
         // nothing at rest — the sheet under it is already that colour, and a
         // rounded fill of the same colour is a coverage mask drawn to change
         // nothing, with four corners it deliberately leaves out
         backgroundColor: active ? theme.hoverBackground : 'transparent',
       },
     },
+    // The native menu's check, in the mark column to the left of the title.
+    // Drawn over the row's own left padding — NSMenu's mark sits inside the
+    // highlight, between its edge and the title.
+    metrics.check &&
+      selected &&
+      h(Icon, {
+        name: 'check',
+        size: capBand(metrics.fontSize),
+        color: active ? theme.hoverText : theme.text,
+        style: { position: 'absolute', left: metrics.markLeft },
+      }),
     h(
       'text',
       {
@@ -156,7 +230,8 @@ function Option({
           capTrim,
           {
             color: active ? theme.hoverText : theme.text,
-            fontWeight: selected ? 'bold' : 'normal',
+            fontSize: metrics.fontSize,
+            fontWeight: selected ? metrics.selectedWeight : metrics.weight,
           },
         ],
       },
@@ -212,27 +287,61 @@ export function Select({
 
   const normalized = options.map(normalizeOption);
   const current = normalized.find((o) => o.value === value);
-  // Rows are sized from the palette's text size, because that is the size
-  // the labels inside them come out at.
-  const rowHeight = itemHeight(theme.fontSize);
-  const contentHeight = normalized.length * rowHeight + MENU_PAD * 2;
+  // Rows are sized from the text size the labels inside them come out at:
+  // the palette's, or NSMenu's under a native popup bezel.
+  const metrics = menuMetrics(theme, nativeControls);
+  const rowHeight = metrics.row;
+  const contentHeight = normalized.length * rowHeight + metrics.pad * 2;
   const menuHeight = Math.min(contentHeight, MAX_MENU_HEIGHT);
   const scrolls = contentHeight > MAX_MENU_HEIGHT;
 
   // shared anchoring: also flips the menu above the trigger when there is
   // no room below, and slides it left when the menu is wider than the
   // trigger and would otherwise open off the right edge
-  const menuAnchorOptions = () => ({
-    placement: 'bottom',
-    height: menuHeight + 2,
-    width: menuWidth(
+  // A native popup button does not drop its menu below the control: it
+  // opens the menu *over* it, with the chosen row on top of the control and
+  // the two titles coincident — the menu's mark column hanging out to the
+  // left, the rows above and below it stacked up and down. The menu's
+  // title inset less the trigger's is how far left it starts. No flip: a
+  // menu over its control has no other side, and is clamped into the
+  // screen as AppKit's is.
+  const menuAnchorOptions = () => {
+    const height = menuHeight + 2;
+    const width = menuWidth(
       triggerRef.current,
       normalized,
       value,
       scrolls,
-      theme.fontSize,
-    ),
-  });
+      metrics,
+    );
+    if (!nativeControls) return { placement: 'bottom', height, width };
+    const node = triggerRef.current;
+    const scale = node?.scale ?? 1;
+    const triggerHeight = node ? node.abs.height / scale : 0;
+    const shadow = bezelShadow(app, 'popup');
+    // Aligned on the *capitals*, which is what the eye lines up: the
+    // trigger's sit on the title baseline (`TITLE_BASELINE` above the bezel
+    // body's bottom), a row's on `capsBottom` — both whole pixels, both
+    // placed rather than centred, so the two agree at every scale.
+    const triggerCapsBottom =
+      triggerHeight - shadow.bottom - TITLE_BASELINE.regular;
+    const rowCapsBottom = metrics.capsBottom;
+    const chosen = Math.max(
+      0,
+      normalized.findIndex((o) => o.value === value),
+    );
+    const chosenRowTop = MENU_BORDER + metrics.pad + chosen * metrics.row;
+    const top = triggerCapsBottom - chosenRowTop - rowCapsBottom;
+    return {
+      placement: 'bottom',
+      offset: 0,
+      flip: false,
+      at: { x: 0, y: top, width: node ? node.abs.width / scale : 0, height: 0 },
+      alignOffset: -metrics.hang.left,
+      height,
+      width,
+    };
+  };
 
   const close = () => setOpen(false);
   const openMenu = () => {
@@ -357,8 +466,20 @@ export function Select({
               alignItems: 'center',
               gap: 8,
               height: bezelNatural(app, 'popup').height,
-              paddingLeft: 10,
+              paddingLeft: TRIGGER_PAD_LEFT,
               paddingRight: 26,
+              // The title sits where NSPopUpButtonCell puts it — on the
+              // same baseline as a push button's, above the body's bottom
+              // edge, the shadow padded off (see Button).
+              paddingTop: bezelShadow(app, 'popup').top,
+              paddingBottom:
+                bezelShadow(app, 'popup').bottom + TITLE_BASELINE.regular,
+              // the keyboard ring hugs the bezel's corners (see Button)
+              borderRadius: 6,
+              ':focus-visible': {
+                outlineWidth: NATIVE_RING.width,
+                outlineOffset: NATIVE_RING.offset,
+              },
             }
           : {
               cursor: 'pointer',
@@ -409,7 +530,13 @@ export function Select({
       }),
     h(
       'text',
-      { style: [capTrim, { color: current ? theme.text : theme.textMuted }] },
+      {
+        style: [
+          capTrim,
+          nativeControls && nativeTitleStyle('regular'),
+          { color: current ? theme.text : theme.textMuted },
+        ],
+      },
       current ? current.label : placeholder,
     ),
     h('box', { style: { flexGrow: 1 } }),
@@ -484,7 +611,11 @@ export function Select({
               // for a Select; this pane is scrolled by wheel and by the
               // arrow keys the trigger already handles.
               focusable: false,
-              style: { flexGrow: 1, padding: MENU_PAD, overflow: 'scroll' },
+              style: {
+                flexGrow: 1,
+                padding: metrics.pad,
+                overflow: 'scroll',
+              },
             },
             normalized.map((option, index) =>
               h(Option, {
@@ -497,6 +628,7 @@ export function Select({
                 nodeRef: index === activeIndex ? activeRef : undefined,
                 onHover: () => setActiveIndex(index),
                 onPick: pick,
+                metrics,
               }),
             ),
           ),

package/src/components/Switch.js

@@ -9,6 +9,8 @@ import { changeEvent } from './change.js';
 import {
   ABS_FILL,
   Bezel,
+  NO_ROW_RING,
+  nativeRingStyle,
   bezelNatural,
   pressWash,
   useNativeControls,
@@ -116,6 +118,7 @@ export function Switch({
             height: nat.height,
             hitSlop: Math.max(0, (24 - nat.height) / 2),
           },
+          NO_ROW_RING,
           style,
         ],
       },
@@ -123,7 +126,11 @@ export function Switch({
         kind: 'switch',
         state: checked ? 1 : 0,
         enabled: !disabled,
-        style: ABS_FILL,
+        style: [
+          ABS_FILL,
+          // the pill: the ring rounds with it
+          nativeRingStyle(theme, control.focusVisible, nat.height / 2),
+        ],
       }),
       h('box', {
         style: [

package/src/components/native.js

@@ -58,6 +58,105 @@ export function bezelNatural(app, kind, controlSize = 'regular') {
   return app?.nativeBezels?.natural(kind, controlSize) ?? null;
 }
 
+/**
+ * The translucent rows above and below the bezel's solid body — a push
+ * button's shadow — as padding, so a label centred in the box is centred in
+ * the control rather than in its footprint. Zero where there is no store.
+ */
+export function bezelShadow(app, kind, controlSize = 'regular') {
+  return (
+    app?.nativeBezels?.shadow?.(kind, controlSize) ?? { top: 0, bottom: 0 }
+  );
+}
+
+/**
+ * Where NSButtonCell — and NSPopUpButtonCell — put a title: its baseline
+ * this far above the bezel body's bottom edge, at each control size. Not
+ * centred: the capitals ride a little above the middle and the descenders
+ * hang below it. Measured off the cells' own rendering of "Done" and "Blue"
+ * (macOS 15): the capitals sit 4.5pt below the top of a 20pt regular body
+ * and 6pt above its bottom, 4pt and 4pt in a 16pt small one.
+ */
+export const TITLE_BASELINE = Object.freeze({ regular: 6, small: 4 });
+
+/**
+ * The system control font at each size — `NSFont.systemFontSize` and
+ * `smallSystemFontSize` — which every bezel is designed around and the
+ * baseline above was measured with. A native label is set in it rather than
+ * in the palette's size: a 14px title in a small bezel has no room to sit
+ * where the cell's does.
+ */
+export const CONTROL_FONT_SIZE = Object.freeze({ regular: 13, small: 11 });
+
+/**
+ * The style of a title placed the way a cell places it: on the bottom of a
+ * content box padded by `TITLE_BASELINE` (a cap-trimmed label's bottom edge
+ * is its baseline, and the trim rounds the cap height to a whole pixel, so
+ * the baseline lands on one), at the control font size. Only the label goes
+ * on the baseline: an icon beside it stays centred, as AppKit centres an
+ * image. Not sized to the cap band: a box that tall clips the ascenders —
+ * the l in "Blue" lost its top row.
+ */
+export function nativeTitleStyle(controlSize = 'regular') {
+  return { alignSelf: 'flex-end', fontSize: CONTROL_FONT_SIZE[controlSize] };
+}
+
+/**
+ * NSMenu's geometry, for the menu a native popup bezel opens — read off
+ * `NSMenu.size` on macOS 15 rather than off a screenshot, so it is the
+ * menu's own arithmetic: a row is 22pt, the sheet pads 5pt top and bottom,
+ * a separator is 11pt, and the font is the 13pt menu font at regular
+ * weight. A title starts 13pt in from the edge — 5 to the highlight, 8
+ * inside it, which is the mark column a menu always reserves — and 28.5pt
+ * of chrome stand between a title's width and the menu's. The highlight's
+ * inset is the pad; its radius is the one number here read off the screen.
+ */
+export const NATIVE_MENU = Object.freeze({
+  fontSize: 13,
+  weight: 'normal',
+  row: 22,
+  pad: 5,
+  padLeft: 8,
+  padRight: 10,
+  radius: 5,
+  separator: 11,
+  // A popup button's menu reserves a column for the check that marks the
+  // chosen item, and its titles start that much further in: 38pt of chrome
+  // against the plain menu's 28.5 (`NSPopUpButton.menu.size`). The mark
+  // itself sits 11pt in from the edge, which is 5 inside the row.
+  markColumn: 9,
+  markLeft: 5,
+});
+
+/**
+ * AppKit's focus ring: one band, outside the control, following the
+ * control's own shape — a circle round a radio, a rounded square round a
+ * checkbox, the bezel's corners round a button. Never round the label, and
+ * never two: a native row that lit its keyboard ring round the whole row
+ * *and* the part's ring round the bezel showed a rectangle round the label
+ * beside a rectangle round the control. Width read off the screen (3pt,
+ * hugging the edge); the colour is the palette's ring, which on macOS is
+ * `keyboardFocusIndicatorColor` over the ground.
+ *
+ * Only for focus that shows: a click on a checkbox lights no ring in
+ * AppKit, Tab does — which is `useControl().focusVisible`.
+ */
+export const NATIVE_RING = Object.freeze({ width: 3, offset: 0 });
+
+/** The ring, as style for the bezel node, shaped to `radius`. */
+export function nativeRingStyle(theme, on, radius) {
+  if (!on) return null;
+  return {
+    outlineWidth: NATIVE_RING.width,
+    outlineColor: theme.focusRing,
+    outlineOffset: NATIVE_RING.offset,
+    borderRadius: radius,
+  };
+}
+
+/** The row round a native part opts out of the renderer's own ring. */
+export const NO_ROW_RING = Object.freeze({ outlineWidth: 0 });
+
 /** Absolute fill inside the control's box — where every bezel layer goes. */
 export const ABS_FILL = Object.freeze({
   position: 'absolute',

package/src/components/theme.js

@@ -10,7 +10,12 @@
 import React, { useContext, useMemo, useState } from 'react';
 import { useAppearanceWhen } from '../appearancehooks.js';
 import { EnvValue, registerFrameProvider } from '../frame/env.js';
-import { DarkTheme, DefaultTheme, resolveTheme } from '../palette.js';
+import {
+  DarkTheme,
+  DefaultTheme,
+  paletteFor,
+  resolveTheme,
+} from '../palette.js';
 
 const h = React.createElement;
 
@@ -67,14 +72,15 @@ const FILL = Object.freeze({ flexGrow: 1 });
  * <ThemeProvider value={light} dark={{ background: '#101418' }}>
  * ```
  *
- * The desktop's **accent** is deliberately not adopted on its own: an app in
- * dark mode did not ask for its buttons to change colour, and most portal
- * backends report no accent at all. Take it explicitly where you want it, and
- * keep a fallback:
+ * The desktop's **accent** is part of what a following provider follows: the
+ * base under `value` is the desktop's palette, accent and all, where the
+ * desktop reports one (`paletteFor`). A brand keeps its own colour by naming
+ * it — `value` wins over the base token for token — and a pinned
+ * `colorScheme` follows nothing, the accent included:
  *
  * ```jsx
- * const { accent } = useSystemAppearance();
- * <ThemeProvider value={{ ...brand, accent: accent ?? brand.accent }}>
+ * <ThemeProvider value={{ accent: '#e17055', accentHover: '#c0563a' }}>  // brand accent, desktop scheme
+ * <ThemeProvider value={brand} colorScheme="light">                       // neither
  * ```
  */
 export function ThemeProvider({
@@ -93,16 +99,17 @@ export function ThemeProvider({
   const system = useAppearanceWhen(follows);
   const wantsDark =
     colorScheme === 'dark' || (follows && system.colorScheme === 'dark');
+  // An outer provider is the base; with none, the base is the desktop's
+  // palette when this provider follows it and the scheme's own built-in one
+  // when pinned. So `value` names what this app changes and everything else
+  // keeps following the desktop. `paletteFor` answers with one object per
+  // desktop answer, so the memo below holds across renders.
+  const base =
+    outer ??
+    (follows ? paletteFor(system) : wantsDark ? DarkTheme : DefaultTheme);
   const theme = useMemo(
-    () =>
-      // An outer provider is the base; with none, the base is the scheme's
-      // own built-in palette. So `value` names what this app changes and
-      // everything else keeps following the desktop.
-      resolveTheme(
-        dark && wantsDark ? { ...value, ...dark } : value,
-        outer ?? (wantsDark ? DarkTheme : DefaultTheme),
-      ),
-    [outer, value, dark, wantsDark],
+    () => resolveTheme(dark && wantsDark ? { ...value, ...dark } : value, base),
+    [base, value, dark, wantsDark],
   );
   // A provider that **names** a direction plants it as a style too, so the
   // node tree mirrors along with the widgets: `useTheme().direction` is what
@@ -181,14 +188,14 @@ function planted(children, theme, style) {
  *
  * Identity matters: widgets plant what this returns on their own root node,
  * and a fresh object every render would re-resolve every `$token` beneath it
- * and defeat the resolution cache. Both built-in palettes are module
- * constants, so the unprovided answer is stable too.
+ * and defeat the resolution cache. `paletteFor` answers with one object per
+ * desktop answer, so the unprovided answer is stable too.
  */
 export function useTheme() {
   const provided = useContext(ThemeContext);
   const system = useAppearanceWhen(provided == null);
   if (provided) return provided;
-  return system.colorScheme === 'dark' ? DarkTheme : DefaultTheme;
+  return paletteFor(system);
 }
 
 /**
@@ -240,6 +247,11 @@ export function useDirection() {
 export function useControl(disabled, onActivate, { styled = false } = {}) {
   const [hover, setHover] = useState(false);
   const [focused, setFocused] = useState(false);
+  // …and whether that focus is the kind that shows: the `:focus-visible`
+  // the focus manager has already decided by the time `onFocus` fires
+  // (Tab lights it, a click does not, except into a text control). A
+  // native control draws its ring for this and not for `focused`.
+  const [focusVisible, setFocusVisible] = useState(false);
   const [pressed, setPressed] = useState(false);
   const activation = {
     focusable: true,
@@ -275,15 +287,20 @@ export function useControl(disabled, onActivate, { styled = false } = {}) {
           },
           onMouseDown: () => setPressed(true),
           onMouseUp: () => setPressed(false),
-          onFocus: () => setFocused(true),
+          onFocus: (ev) => {
+            setFocused(true);
+            setFocusVisible(ev?.target?.states?.[':focus-visible'] === true);
+          },
           onBlur: () => {
             setFocused(false);
+            setFocusVisible(false);
             setPressed(false);
           },
         };
   return {
     hover: !styled && hover && !disabled,
     focused: !styled && focused && !disabled,
+    focusVisible: !styled && focusVisible && !disabled,
     pressed: !styled && pressed && !disabled,
     props,
     // `cursor` is style, so it travels in the style channel — put it first

package/src/desktopsettings.js

@@ -17,7 +17,11 @@
 // XQuartz — the defaults below stand.
 //
 // So this reads the map `xsettings.js` already maintains, rather than
-// standing up a source of its own.
+// standing up a source of its own. The one exception is macOS, which has no
+// XSETTINGS and answers exactly one of these — "reduce motion", through
+// `NSWorkspace` — so the Cocoa app exposes that behind a two-method seam
+// (`accessibilityDisplayOptions`, `watchAccessibilityDisplay`) and this
+// module reads it the way it reads the map: synchronously, cached, live.
 //
 // ## Two of these are read synchronously, which is what shapes the module
 //
@@ -85,6 +89,22 @@ function positive(map, key) {
  * conversion, and forgetting to is a caret that blinks at half speed and
  * looks broken rather than wrong.
  */
+/**
+ * macOS's accessibility display options → the settings. Only `animations`
+ * comes from the system there: it is the one of these macOS publishes at all
+ * (System Settings › Accessibility › Display › Reduce motion, which the
+ * bridge reads from `NSWorkspace`), and the rest keep this renderer's
+ * defaults rather than being guessed from something that is not them. Pure,
+ * and exported for the test.
+ */
+export function fromMacOS(options) {
+  return Object.freeze({
+    ...DEFAULTS,
+    animations: options?.reduceMotion !== true,
+    source: 'macos',
+  });
+}
+
 export function fromXSettings(map) {
   if (!map) return DEFAULTS;
   const cycle = positive(map, 'Net/CursorBlinkTime');
@@ -126,7 +146,9 @@ export function desktopSettings(app) {
   const session = sessions.get(app);
   if (!session) return DEFAULTS;
   if (!session.snapshot) {
-    session.snapshot = fromXSettings(xsettings(app));
+    session.snapshot = session.macos
+      ? fromMacOS(app.accessibilityDisplayOptions())
+      : fromXSettings(xsettings(app));
   }
   return session.snapshot;
 }
@@ -141,6 +163,16 @@ export function beginDesktopSettings(app) {
   if (sessions.has(app)) return;
   const session = { snapshot: null, listeners: new Set(), stop: null };
   sessions.set(app, session);
+  // The Cocoa app: the answer is synchronous from the start, and the change
+  // arrives as a backend event rather than a property on a selection owner.
+  if (typeof app?.accessibilityDisplayOptions === 'function') {
+    session.macos = true;
+    session.stop = app.watchAccessibilityDisplay?.(() => {
+      session.snapshot = null;
+      notify(session);
+    });
+    return;
+  }
   beginXSettings(app).then(
     () => {
       if (!sessions.has(app)) return;