react-x11 2.15.3 → 2.16.1

package/src/styles.js

@@ -247,6 +247,12 @@ const PAINT_PROPS = new Set([
   'outlineWidth',
   'outlineColor',
   'outlineOffset',
+  // How opaque the node is **with everything in it**: the subtree is drawn
+  // once and composited at this alpha (`NodePaint._paintGroup`), so a card, its
+  // border, its icon and its text fade as one — the thing a colour's own
+  // alpha cannot do for more than one flat fill (#587). A number from 0 to 1,
+  // which transitions and loops like any other.
+  'opacity',
 ]);
 
 // Text style props. All affect measurement except color.
@@ -275,8 +281,105 @@ export const TEXT_LAYOUT_PROPS = new Set([
   // fits on a line, so it is a measurement input like the rest of this set.
   'textOverflow',
   'maxLines',
+  // CSS's letter-spacing, in px: added after every character, the last on a
+  // line included, which is how both text engines add it (#588)
+  'letterSpacing',
+  // Figures and the rest of the OpenType features. `fontVariantNumeric` is
+  // CSS's keywords for the numeric ones — `tabular-nums` for a readout that
+  // holds its width while it changes — and `fontFeatureSettings` names any
+  // feature by tag, winning over the keyword where the two meet, as in CSS
+  'fontVariantNumeric',
+  'fontFeatureSettings',
 ]);
 
+/**
+ * `fontVariantNumeric` keywords → the OpenType feature each one turns on, and
+ * the group it belongs to. CSS allows several keywords at once but one from
+ * each group, since the two in a group contradict each other: `'tabular-nums
+ * slashed-zero'` is a value, `'lining-nums oldstyle-nums'` is not.
+ */
+const NUMERIC_VARIANTS = {
+  'lining-nums': ['lnum', 'figures'],
+  'oldstyle-nums': ['onum', 'figures'],
+  'proportional-nums': ['pnum', 'spacing'],
+  'tabular-nums': ['tnum', 'spacing'],
+  'diagonal-fractions': ['frac', 'fractions'],
+  'stacked-fractions': ['afrc', 'fractions'],
+  ordinal: ['ordn', 'ordinal'],
+  'slashed-zero': ['zero', 'slashed-zero'],
+};
+
+/** The feature tags a `fontVariantNumeric` value turns on, or null when the
+ *  value is not one CSS would accept. `'normal'` turns none on. */
+function numericVariantTags(value) {
+  if (typeof value !== 'string') return null;
+  const words = value.trim().split(/\s+/);
+  if (words.length === 1 && words[0] === 'normal') return [];
+  const tags = [];
+  const groups = new Set();
+  for (const word of words) {
+    const [tag, group] = NUMERIC_VARIANTS[word] ?? [];
+    if (!tag || groups.has(group)) return null;
+    groups.add(group);
+    tags.push(tag);
+  }
+  return tags;
+}
+
+/** An OpenType feature tag: four printable ASCII characters. */
+const FEATURE_TAG = /^[\x20-\x7e]{4}$/;
+
+/** Whether `value` is a `fontFeatureSettings`: an array of tags to turn on,
+ *  or an object of tag → on or off, or the number of the alternate a feature
+ *  picks. */
+function isFeatureSettings(value) {
+  if (Array.isArray(value)) {
+    return value.every(
+      (tag) => typeof tag === 'string' && FEATURE_TAG.test(tag),
+    );
+  }
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value).every(
+    ([tag, v]) =>
+      FEATURE_TAG.test(tag) &&
+      (typeof v === 'boolean' || (Number.isInteger(v) && v >= 0)),
+  );
+}
+
+// the resolved `features` for one (variant, settings) pair, kept so that the
+// same pair is the same object every time: a cascade compares two resolved
+// styles with `!==` (`resolvedTextDelta`), and a fresh object per node would
+// read as a change and re-measure text that did not move
+const resolvedFeatures = new Map();
+
+/**
+ * What the text engines are handed: every feature the two properties set, as
+ * tag → value (1 on, 0 off, or the alternate), `fontFeatureSettings` over
+ * the keywords. `undefined` when neither says anything, which is nearly
+ * every node.
+ */
+export function featuresOf(variantNumeric, featureSettings) {
+  if (variantNumeric === undefined && featureSettings === undefined) {
+    return undefined;
+  }
+  const key = `${variantNumeric ?? ''}\u0000${JSON.stringify(featureSettings ?? null)}`;
+  if (resolvedFeatures.has(key)) return resolvedFeatures.get(key);
+  const features = {};
+  for (const tag of numericVariantTags(variantNumeric) ?? []) features[tag] = 1;
+  if (Array.isArray(featureSettings)) {
+    for (const tag of featureSettings) features[tag] = 1;
+  } else if (featureSettings) {
+    for (const [tag, value] of Object.entries(featureSettings)) {
+      features[tag] = value === true ? 1 : value === false ? 0 : value;
+    }
+  }
+  const out =
+    Object.keys(features).length > 0 ? Object.freeze(features) : undefined;
+  if (resolvedFeatures.size > 256) resolvedFeatures.clear();
+  resolvedFeatures.set(key, out);
+  return out;
+}
+
 /**
  * Text style props that change how the text is **drawn** and provably not
  * where any of it lands. They still invalidate the cached layout — the value
@@ -298,7 +401,8 @@ export const TEXT_PAINT_PROPS = new Set(['textRendering']);
  * dims the labels under it the way it would in CSS.
  *
  * This is CSS's inherited set narrowed to what a *descendant* can act on: the
- * face, the size, the ink and the glyph rounding. `textAlign`, `lineHeight`,
+ * face, the size, the ink, the glyph rounding, the spacing between letters
+ * and the OpenType features. `textAlign`, `lineHeight`,
  * `textWrap`, `textOverflow`, `maxLines` and `textBoxTrim` stay out even
  * though CSS inherits the first two — here they are read by the node that
  * owns the **box** the text flows in, and a box is not something a descendant
@@ -313,6 +417,9 @@ export const INHERITED_TEXT_PROPS = new Set([
   'fontVariationSettings',
   'textRendering',
   'color',
+  'letterSpacing',
+  'fontVariantNumeric',
+  'fontFeatureSettings',
 ]);
 
 /**
@@ -340,7 +447,7 @@ export function localTextStyleChanged(style, before) {
 export function inheritedTextChanged(style, before) {
   if (style === before) return false;
   for (const key of INHERITED_TEXT_PROPS) {
-    if (key === 'fontVariationSettings') {
+    if (key === 'fontVariationSettings' || key === 'fontFeatureSettings') {
       if (!axesEqual(style[key], before[key])) return true;
     } else if (style[key] !== before[key]) return true;
   }
@@ -370,7 +477,9 @@ export function resolvedTextDelta(a, b) {
     a.size !== b.size ||
     a.weight !== b.weight ||
     a.style !== b.style ||
-    !axesEqual(a.variations, b.variations)
+    !axesEqual(a.variations, b.variations) ||
+    a.letterSpacing !== b.letterSpacing ||
+    a.features !== b.features
   ) {
     return TEXT_REMEASURE;
   }
@@ -746,6 +855,64 @@ const GRID_VALUES = new Set([...GRID_CONTAINER_PROPS, ...GRID_ITEM_PROPS]);
  * grammar is concerned), so this checks the shape and never the colours.
  */
 function validateValue(key, value, where) {
+  if (key === 'letterSpacing') {
+    if (
+      value != null &&
+      !(typeof value === 'number' && Number.isFinite(value)) &&
+      !isToken(value)
+    ) {
+      throw new Error(
+        `react-x11: invalid letterSpacing ${JSON.stringify(value)} in ${where} ` +
+          '(expected a number of pixels, like letterSpacing: 1.5, or a $token)',
+      );
+    }
+    return;
+  }
+  if (key === 'fontVariantNumeric') {
+    if (
+      value != null &&
+      numericVariantTags(value) === null &&
+      !isToken(value)
+    ) {
+      throw new Error(
+        `react-x11: invalid fontVariantNumeric ${JSON.stringify(value)} in ` +
+          `${where} (expected 'normal', or keywords from ` +
+          `${Object.keys(NUMERIC_VARIANTS).join(', ')} with at most one of ` +
+          'lining/oldstyle, proportional/tabular and diagonal/stacked, like ' +
+          "'tabular-nums' or 'tabular-nums slashed-zero')",
+      );
+    }
+    return;
+  }
+  if (key === 'fontFeatureSettings') {
+    if (value != null && !isFeatureSettings(value) && !isToken(value)) {
+      throw new Error(
+        `react-x11: invalid fontFeatureSettings ${JSON.stringify(value)} in ` +
+          `${where} (expected four-letter OpenType tags — an array of tags to ` +
+          "turn on, ['tnum'], or an object of tag to on/off or an alternate, " +
+          '{ tnum: true, liga: false, salt: 2 })',
+      );
+    }
+    return;
+  }
+  if (key === 'opacity') {
+    // unset, the way a conditional writes it: `opacity: dim ? 0.5 : undefined`
+    if (value == null) return;
+    // A string that is not a token is the one mistake worth stopping for:
+    // `'50%'` or `'0.5'` would otherwise compare as not-below-1 and paint
+    // the node fully opaque, silently. A number outside 0..1 is clamped
+    // where it is painted, as CSS clamps it.
+    if (
+      !(typeof value === 'number' && !Number.isNaN(value)) &&
+      !isToken(value)
+    ) {
+      throw new Error(
+        `react-x11: invalid opacity ${JSON.stringify(value)} in ${where} ` +
+          '(expected a number from 0 to 1 — opacity: 0.5 is half — or a $token)',
+      );
+    }
+    return;
+  }
   const grid = GRID_VALUES.has(key);
   if (!grid && key !== 'backgroundImage' && key !== 'boxShadow') return;
   try {
@@ -962,6 +1129,9 @@ const NOT_ANIMATABLE = new Set([
   'fontFamily',
   'fontWeight',
   'fontStyle',
+  // a keyword and a bag of tags: there is no halfway figure
+  'fontVariantNumeric',
+  'fontFeatureSettings',
   'textAlign',
   // nothing is drawn from it, so there is no frame in which a halfway value
   // would be visible — and it may be an object, which does not lerp
@@ -1056,6 +1226,9 @@ const parsedAnimations = new WeakMap();
  * a thing that does not move: a loop nobody wrote a stop for is exactly the
  * feature where silence is unreadable.
  */
+/** What one property's loop may say. */
+const LOOP_OPTIONS = ['from', 'to', 'duration', 'easing', 'alternate', 'delay'];
+
 function parseAnimation(spec, where) {
   if (typeof spec !== 'object' || spec === null || Array.isArray(spec)) {
     throw new Error(
@@ -1077,15 +1250,15 @@ function parseAnimation(spec, where) {
     if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
       throw new Error(
         `react-x11: invalid animation for ${at} — expected ` +
-          '{ from?, to, duration, easing?, alternate? }, got ' +
+          '{ from?, to, duration, easing?, alternate?, delay? }, got ' +
           JSON.stringify(entry),
       );
     }
     for (const key of Object.keys(entry)) {
-      if (!['from', 'to', 'duration', 'easing', 'alternate'].includes(key)) {
+      if (!LOOP_OPTIONS.includes(key)) {
         throw new Error(
           `react-x11: unknown animation option "${key}" for ${at} ` +
-            '(expected from, to, duration, easing, alternate)',
+            `(expected ${LOOP_OPTIONS.join(', ')})`,
         );
       }
     }
@@ -1109,6 +1282,14 @@ function parseAnimation(spec, where) {
           `${at} (expected one of ${EASING_NAMES.join(', ')})`,
       );
     }
+    const delay = entry.delay ?? 0;
+    if (typeof delay !== 'number' || !Number.isFinite(delay)) {
+      throw new Error(
+        `react-x11: animation for ${at} needs "delay" in ms — before the ` +
+          'loop starts, or negative to start it that far in — got ' +
+          JSON.stringify(entry.delay),
+      );
+    }
     entries.push({
       prop,
       from: entry.from,
@@ -1117,6 +1298,7 @@ function parseAnimation(spec, where) {
       easing,
       ease: EASINGS[easing],
       alternate: Boolean(entry.alternate),
+      delay,
     });
   }
   return entries;
@@ -1184,7 +1366,8 @@ export function sameAnimation(a, b) {
     a.to === b.to &&
     a.duration === b.duration &&
     a.easing === b.easing &&
-    a.alternate === b.alternate
+    a.alternate === b.alternate &&
+    a.delay === b.delay
   );
 }
 
@@ -1193,9 +1376,14 @@ export function sameAnimation(a, b) {
  * the looping: the phase comes from a modulo of the elapsed time rather than
  * from a per-cycle restart, so a bar that has been spinning for an hour is
  * exactly where the clock says and no rounding has accumulated.
+ *
+ * The delay is where the loop's own time starts: `from` until a positive one
+ * has passed, and already that far in for a negative one — CSS's
+ * `animation-delay` with `animation-fill-mode: backwards`, which is also
+ * what Core Animation shows for the same declaration.
  */
 export function animationValueAt(spec, elapsed) {
-  const cycles = Math.max(0, elapsed) / spec.duration;
+  const cycles = Math.max(0, elapsed - spec.delay) / spec.duration;
   let t = cycles % 1;
   if (spec.alternate && Math.floor(cycles) % 2 === 1) t = 1 - t;
   return interpolate(spec.from, spec.to, spec.ease(t)) ?? spec.from;
@@ -1670,6 +1858,7 @@ export const SCALED_LENGTH_PROPS = [
   'outlineWidth',
   'outlineOffset',
   'fontSize',
+  'letterSpacing',
 ];
 
 const SCALED_LENGTHS = new Set(SCALED_LENGTH_PROPS);
@@ -1834,6 +2023,9 @@ export function paintPropsChanged(props, oldProps = {}) {
 
 /** Resolved text style (TextLayout base style) from props + inherited. */
 export function textStyleFrom(props, inherited) {
+  const variantNumeric = props.fontVariantNumeric ?? inherited.variantNumeric;
+  const featureSettings =
+    props.fontFeatureSettings ?? inherited.featureSettings;
   return {
     family: props.fontFamily ?? inherited.family,
     size: props.fontSize ?? inherited.size,
@@ -1844,6 +2036,14 @@ export function textStyleFrom(props, inherited) {
     variations: props.fontVariationSettings ?? inherited.variations,
     textRendering: props.textRendering ?? inherited.textRendering,
     color: props.color ?? inherited.color,
+    letterSpacing: props.letterSpacing ?? inherited.letterSpacing,
+    // Inherited apart, as CSS inherits the two properties apart — a child's
+    // `fontVariantNumeric` replaces the keyword above it and leaves an
+    // inherited `fontFeatureSettings` alone — and resolved together into what
+    // the engines read.
+    variantNumeric,
+    featureSettings,
+    features: featuresOf(variantNumeric, featureSettings),
   };
 }
 
@@ -1865,6 +2065,10 @@ export const DEFAULT_TEXT_STYLE = {
   variations: undefined,
   textRendering: undefined,
   color: 'black',
+  letterSpacing: undefined,
+  variantNumeric: undefined,
+  featureSettings: undefined,
+  features: undefined,
 };
 
 /**

package/src/symbols.js

@@ -0,0 +1,200 @@
+// Symbols by name: the platform's own icons, drawn in the text colour inside
+// a window (#591) — the names `useTray`'s `icon` and a menu item's `iconName`
+// already take, and nothing that draws in a window did.
+//
+// Two providers, one per icon system, behind the same two questions, how
+// big and draw it here:
+//
+// - **SF Symbols** on the Cocoa backend, which brings its own
+//   (`app.symbols`, src/cocoa/symbols.js): a symbol is a template, drawn in
+//   the fill colour at the weight and point size of the text beside it.
+// - **The freedesktop icon theme** everywhere else (src/icontheme.js): the
+//   user's theme, looked up at the size the text calls for. A `-symbolic` icon
+//   is preferred and drawn the same way, its shape in the text colour; an icon
+//   that is only drawn in its own colours is shown as it is.
+//
+// A name one system does not have simply is not there, and takes no room —
+// the same bargain a tray icon's name makes — so an app that runs on both
+// picks its names by platform, as it does for the tray.
+
+import { cssColorStraight, decodeImage, SvgView } from 'ntk';
+import * as nodeFs from 'node:fs';
+
+import { IconTheme } from './icontheme.js';
+import { Surface } from './ntk.js';
+import { xsettings } from './xsettings.js';
+
+/** A `fontWeight` as the number both icon systems configure with. */
+export function symbolWeight(weight) {
+  if (typeof weight === 'number') return weight;
+  if (weight === 'bold') return 700;
+  return 400;
+}
+
+const warned = new Set();
+/** A development warning, once per message. */
+export function warnOnce(message) {
+  if (process.env.NODE_ENV === 'production' || warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+
+// --- the freedesktop icon theme -----------------------------------------------
+
+/**
+ * The size a theme is asked for beside text of `pointSize`: 16 for 14px text,
+ * which is the pairing every toolkit's menus and toolbars are drawn at, and in
+ * proportion from there. An icon theme's icons are square.
+ */
+export const iconSizeFor = (pointSize) =>
+  Math.max(1, Math.round((pointSize * 8) / 7));
+
+/**
+ * The user's icon theme on this connection: what the settings daemon says
+ * (`Net/IconThemeName`, which GNOME and Xfce write), and failing that
+ * Adwaita, which `hicolor` then backs up. An explicit `theme` from the test
+ * seam wins.
+ */
+export function iconThemeName(app) {
+  const named = xsettings(app)?.get?.('Net/IconThemeName');
+  return typeof named === 'string' && named ? named : 'Adwaita';
+}
+
+class FreedesktopSymbols {
+  constructor(app, { theme, baseDirs, pixmapDirs, fs = nodeFs } = {}) {
+    this.app = app;
+    this.fs = fs;
+    this.theme = new IconTheme({
+      theme: theme ?? iconThemeName(app),
+      baseDirs,
+      pixmapDirs,
+      fs,
+    });
+    this.documents = new Map(); // path -> SvgView | Image | null
+    // path|size|colour -> Surface, least recently drawn first
+    this.rasters = new Map();
+  }
+
+  /** `{ path, symbolic }` for a name at a logical size, or null. A symbolic
+   *  variant is preferred: it is the one that takes the text colour. */
+  _resolve(name, pointSize, scale) {
+    const size = iconSizeFor(pointSize);
+    const whole = Math.max(1, Math.round(scale));
+    const symbolic = name.endsWith('-symbolic');
+    for (const candidate of symbolic ? [name] : [`${name}-symbolic`, name]) {
+      const path = this.theme.find(candidate, size, whole);
+      if (path) return { path, symbolic: candidate.endsWith('-symbolic') };
+    }
+    return null;
+  }
+
+  size(name, options) {
+    if (!this._resolve(name, options.pointSize, options.displayScale)) {
+      return null;
+    }
+    const side = iconSizeFor(options.pointSize);
+    return { width: side, height: side };
+  }
+
+  draw(ctx, name, rect, options) {
+    const found = this._resolve(name, options.pointSize, options.displayScale);
+    if (!found) return false;
+    // square, centred in the box, on whole device pixels
+    const side = Math.max(1, Math.floor(Math.min(rect.width, rect.height)));
+    const x = Math.round(rect.x + (rect.width - side) / 2);
+    const y = Math.round(rect.y + (rect.height - side) / 2);
+    const raster = this._raster(found, side, options.color);
+    if (!raster) return false;
+    ctx.drawImage(raster, x, y, side, side);
+    return true;
+  }
+
+  /** The icon drawn at `side` device pixels — in `color` for a symbolic one —
+   *  kept for the next paint. */
+  _raster(found, side, color) {
+    const ink = found.symbolic
+      ? (cssColorStraight(color) ?? [0, 0, 0, 1])
+      : null;
+    const key = `${found.path}\u0000${side}\u0000${ink?.join(',') ?? ''}`;
+    const kept = this.rasters.get(key);
+    if (kept) {
+      this.rasters.delete(key);
+      this.rasters.set(key, kept);
+      return kept;
+    }
+    const document = this._document(found.path);
+    if (!document) return null;
+    let surface;
+    try {
+      surface = new Surface(this.app, { width: side, height: side });
+    } catch {
+      return null; // no offscreen surfaces here: the headless mock
+    }
+    surface.render((sctx) => {
+      sctx.clearRect(0, 0, side, side);
+      if (document instanceof SvgView) document.draw(sctx, 0, 0, side, side);
+      else sctx.drawImage(document, 0, 0, side, side);
+      if (ink) {
+        // the shape's coverage, in the text colour: what AppKit does with a
+        // template, and what GTK does with a symbolic icon
+        sctx.globalCompositeOperation = 'source-in';
+        sctx.fillStyle = `rgba(${Math.round(ink[0] * 255)}, ${Math.round(ink[1] * 255)}, ${Math.round(ink[2] * 255)}, ${ink[3]})`;
+        sctx.fillRect(0, 0, side, side);
+      }
+    });
+    this.rasters.set(key, surface);
+    if (this.rasters.size > 64) {
+      const [oldest, evicted] = this.rasters.entries().next().value;
+      this.rasters.delete(oldest);
+      evicted.destroy?.();
+    }
+    return surface;
+  }
+
+  _document(path) {
+    if (this.documents.has(path)) return this.documents.get(path);
+    let document = null;
+    try {
+      const bytes = this.fs.readFileSync(path);
+      if (path.endsWith('.svg')) {
+        document = new SvgView(null);
+        document.setSvg(bytes.toString('utf8'));
+      } else {
+        document = decodeImage(bytes);
+      }
+    } catch (err) {
+      warnOnce(`react-x11: the icon ${path} did not load: ${err.message}`);
+    }
+    this.documents.set(path, document);
+    return document;
+  }
+
+  destroy() {
+    for (const surface of this.rasters.values()) surface.destroy?.();
+    this.rasters.clear();
+  }
+}
+
+// --- per app --------------------------------------------------------------------
+
+const providers = new WeakMap();
+
+/**
+ * The symbol provider for a connection: the one the app brings, which is the
+ * Cocoa app's SF Symbols, or the freedesktop icon theme, made on first use.
+ */
+export function symbolsFor(app) {
+  let provider = providers.get(app);
+  if (!provider) {
+    provider = app?.symbols ?? new FreedesktopSymbols(app);
+    providers.set(app, provider);
+  }
+  return provider;
+}
+
+/** Look icons up in a theme of the test's own, at base directories it names. */
+export function setIconThemeForTests(app, options) {
+  providers.get(app)?.destroy?.();
+  if (options == null) providers.delete(app);
+  else providers.set(app, new FreedesktopSymbols(app, options));
+}

package/src/testing/mock-app.js

@@ -288,6 +288,16 @@ export function createMockApp() {
           wnd.grabbed = false;
           wnd.calls.push(['ungrabPointer']);
         },
+        // …and a popup that takes the keyboard holds this one
+        grabKeyboard(options, cb) {
+          wnd.keyboardGrabbed = true;
+          wnd.calls.push(['grabKeyboard']);
+          cb?.(null, 0);
+        },
+        ungrabKeyboard() {
+          wnd.keyboardGrabbed = false;
+          wnd.calls.push(['ungrabKeyboard']);
+        },
         // ntk >= 7.5.0. `xi2: 'auto'` creates a window on core events and
         // calls this the first time it is scrolled, so the call is the
         // observable half of the upgrade — `wnd.xi2Selected` is what a test

package/src/trayhooks.js

@@ -74,9 +74,10 @@ import { StatusNotifierItem, allocateItemSlot } from './statusnotifier.js';
  *
  * With `menu`, a click opens it — the same `items` vocabulary `MenuBar` and
  * `useDockMenu` take, an item's `onSelect` firing when picked. Without one,
- * `onClick` is called with the button and, where the backend knows it, the
- * item's screen rect. `null` means no item. Every field follows its value
- * while mounted; the item is removed on unmount.
+ * `onClick` is called with the button and where the click was, in logical
+ * screen pixels — with the item's rect, where the backend knows it. `null`
+ * means no item. Every field follows its value while mounted; the item is
+ * removed on unmount.
  *
  * `available` is whether this backend has a tray at all, and it **settles**:
  * false on the first frame, true once a tray has been found. Branch on it for
@@ -89,6 +90,8 @@ export function useTray(options) {
   const itemRef = useRef(null);
   const [rect] = useState(null);
   const [remote, setRemote] = useState(false);
+  // whether the freedesktop registration has answered, either way
+  const [answered, setAnswered] = useState(false);
   const [error, setError] = useState(null);
   // The feature vocabulary for whichever rung answered. Probed once per
   // backend rather than per render — it describes the mechanism, not the
@@ -166,6 +169,10 @@ export function useTray(options) {
     const appId = currentRegistration()?.appId ?? 'react-x11';
     const item = new StatusNotifierItem({
       getOptions: () => live.current,
+      // The display a click's position is read against: the host sends it in
+      // a unit of its own choosing — see "The position has no unit" in
+      // statusnotifier.js.
+      app,
       appId,
       slot: slotRef.current,
       decodeIcon: decodeIconBytes,
@@ -180,16 +187,19 @@ export function useTray(options) {
     sniRef.current = item;
     previous.current = { ...live.current };
     void item.start().then((ok) => {
-      if (!cancelled) setRemote(ok);
+      if (cancelled) return;
+      setRemote(ok);
+      setAnswered(true);
     });
     return () => {
       cancelled = true;
       sniRef.current = null;
       setRemote(false);
+      setAnswered(false);
       setError(null);
       void item.stop();
     };
-  }, [native, options == null]);
+  }, [app, native, options == null]);
 
   // The item reads its fields through `getOptions`, so a render only has to
   // say *which* of them moved — see `StatusNotifierItem.update`.
@@ -215,6 +225,12 @@ export function useTray(options) {
   const backend = native ? 'cocoa' : remote ? caps.backend : null;
   return {
     available: native || remote,
+    // Whether `available` is an answer yet: at once on the Cocoa rung and for
+    // no item at all, and on the freedesktop one once the host has taken or
+    // refused the registration — so an app whose whole UI is its tray can
+    // render nothing until then, rather than a fallback window that flashes
+    // up and away on every start.
+    settled: native || !options || answered,
     backend,
     features: native || remote ? caps.features : NO_CAPABILITY.features,
     error,

package/src/types/capabilities.d.ts

@@ -124,4 +124,16 @@ export declare function desktopCapability<N extends DesktopCapabilityName>(
  */
 export declare function useDesktopCapability<N extends DesktopCapabilityName>(
   name: N,
-): DesktopCapabilityFor<N>;
+): DesktopCapabilityState<N>;
+
+/** {@link useDesktopCapability}'s answer, and whether it is one yet. */
+export type DesktopCapabilityState<N extends DesktopCapabilityName> =
+  DesktopCapabilityFor<N> & {
+    /**
+     * False until the first probe answers, and true from then on, re-probes
+     * included — so an app can hold its fallback back rather than flash it.
+     * True on the first frame where nothing had to be asked: the tray and
+     * the Dock tile on macOS.
+     */
+    settled: boolean;
+  };