react-x11 2.6.1 → 2.7.0

package/src/dnd.js

@@ -269,6 +269,9 @@ export class DropSession {
     this.path = [];
     // what an `ask` source offered, read once per drag (see _readAskOffer)
     this._askOffer = null;
+    // driven through the local entry points (a DragSession here, or a
+    // backend's own drop machinery) rather than the XDND wire
+    this._viaLocal = false;
     this.accepted = null;
     this.acceptedAction = 'copy';
     this.requestedAction = 'copy';
@@ -491,7 +494,13 @@ export class DropSession {
   // back as a return value instead of an XdndStatus.
 
   localOver(rootX, rootY, offer, time) {
-    this._source = 'internal';
+    // `offer.source` is what the handlers see: 'internal' for a DragSession
+    // in this process, 'external' when a backend's own drop machinery drives
+    // these same entry points for another application's drag (src/cocoa/
+    // dnd.js) — the path diffing and the dispatch are one implementation
+    // either way
+    this._source = offer.source ?? 'internal';
+    this._viaLocal = true;
     this.sourceWid = 0;
     this.types = offer.types;
     this.requestedAction = offer.action;
@@ -500,10 +509,11 @@ export class DropSession {
   }
 
   localLeave() {
-    if (this._source !== 'internal') return;
+    if (!this._viaLocal) return;
     discrete(() => this._clearPath())();
     this.accepted = null;
     this.lastPoint = null;
+    this._viaLocal = false;
     this._source = 'external';
   }
 
@@ -512,7 +522,7 @@ export class DropSession {
    * from the caller's point of view — `onDragEnd` follows immediately,
    * like the DOM's dragend after drop. */
   localDrop(offer, extras, time) {
-    this._source = 'internal';
+    this._source = offer.source ?? 'internal';
     this.types = offer.types;
     const point = this.lastPoint;
     const accepted = this.accepted;
@@ -555,6 +565,7 @@ export class DropSession {
     })();
     this.accepted = null;
     this.lastPoint = null;
+    this._viaLocal = false;
     this._source = 'external';
     return {
       handled: outcome.accept,
@@ -1186,6 +1197,7 @@ export class DragSession {
     this._atoms = null;
     this._cursor = null;
     this.ext = null;
+    this._nativeSession = false;
   }
 
   /** The pressed node (or an ancestor) is draggable: remember where, and
@@ -1219,6 +1231,7 @@ export class DragSession {
   /** Every mousemove while armed or dragging. Returns true when the drag
    * consumed the motion — the caller then skips hover and mousemove. */
   motion(native) {
+    if (this._nativeSession) return true;
     if (this.phase === 'armed') {
       const moved =
         Math.abs(native.x - this.press.x) + Math.abs(native.y - this.press.y);
@@ -1259,9 +1272,84 @@ export class DragSession {
     this.phase = 'dragging';
     source.setStyleState(':dragging', true);
     this._setCursor('grab');
+    // A backend with a drag session of its own (the cocoa backend's
+    // NSDraggingSession, src/cocoa/dnd.js) takes the gesture from here:
+    // the pointer's motion and release stop arriving and come back as
+    // `nativeMoved`/`nativeEnded`, and a drop on one of our own windows
+    // comes through that window's destination events, routed to this
+    // session's live payload by `app._activeDrag`.
+    const wnd = this.node.window;
+    if (typeof wnd?.beginDrag === 'function') {
+      this._nativeSession = true;
+      this.app._activeDrag = this;
+      try {
+        wnd.beginDrag(this);
+      } catch (err) {
+        this._nativeSession = false;
+        this.app._activeDrag = null;
+        this._reset();
+        throw err;
+      }
+    }
     return true;
   }
 
+  /** `drag-session-moved` on a native session: the source's `onDrag`, in
+   * global device pixels, with whether a window of ours has accepted. */
+  nativeMoved(ev) {
+    if (this.phase !== 'dragging' || !this._nativeSession) return;
+    const s = this.node.scale;
+    const origin = this.node.window?._screenOrigin ?? { x: 0, y: 0 };
+    const rootX = Math.round(ev.x * s);
+    const rootY = Math.round(ev.y * s);
+    const native = {
+      x: rootX - origin.x,
+      y: rootY - origin.y,
+      rootx: rootX,
+      rooty: rootY,
+      buttons: 256,
+      time: 0,
+    };
+    const source = this.source;
+    if (source && !source.destroyed && source.props.onDrag) {
+      callHandler(
+        source,
+        'onDrag',
+        source.props.onDrag,
+        this.node.events._makeEvent('drag', native, source, {
+          types: this.types,
+          action: this.currentAction,
+          source: this.localSession ? 'internal' : 'external',
+          accepted: this.accepted,
+          screenX: rootX / this.node.events.scale,
+          screenY: rootY / this.node.events.scale,
+        }),
+      );
+    }
+  }
+
+  /** `drag-session-ended`: the release, with what the destination did. */
+  nativeEnded(ev) {
+    if (!this._nativeSession) return;
+    this._nativeSession = false;
+    if (this.app._activeDrag === this) this.app._activeDrag = null;
+    if (this.phase !== 'dragging') return this._reset();
+    const source = this.source;
+    source?.setStyleState?.(':dragging', false);
+    this.localSession?.localLeave();
+    const s = this.node.scale;
+    const origin = this.node.window?._screenOrigin ?? { x: 0, y: 0 };
+    const rootX = Math.round((ev.x ?? 0) * s);
+    const rootY = Math.round((ev.y ?? 0) * s);
+    const operation =
+      ev.operation && ev.operation !== 'none' ? ev.operation : null;
+    this._end(
+      { x: rootX - origin.x, y: rootY - origin.y, rootx: rootX, rooty: rootY },
+      ev.dropped ? operation : null,
+      Boolean(ev.dropped),
+    );
+  }
+
   /** dragData values resolve once per drag: thunks are called on first
    * use — at delivery for an internal drop, at promotion for an external
    * one — and never at mousedown. */
@@ -1354,6 +1442,7 @@ export class DragSession {
   /** Button release. Returns true when a drag ran (the caller suppresses
    * mouseup/click, like the DOM after a drag gesture). */
   release(native) {
+    if (this._nativeSession) return true;
     if (this.phase !== 'dragging') {
       this._reset();
       return false;

package/src/errors.js

@@ -87,15 +87,18 @@ const reportedStyleErrors = new WeakMap();
  * run or a supervisor still counts this as a failure. `REACT_X11_STRICT_TOKENS=1`
  * restores the throw.
  */
-export function reportStyleError(node, message) {
+export function reportStyleError(
+  node,
+  message,
+  consequence = 'The property is dropped and the app carries on',
+) {
   const seen = reportedStyleErrors.get(node);
   if (seen?.has(message)) return;
   if (seen) seen.add(message);
   else reportedStyleErrors.set(node, new Set([message]));
   const owner = ownerName(node);
   console.error(
-    `${message}${owner ? ` — in ${owner}` : ''}. ` +
-      'The property is dropped and the app carries on; set ' +
+    `${message}${owner ? ` — in ${owner}` : ''}. ${consequence}; set ` +
       'REACT_X11_STRICT_TOKENS=1 to make this throw instead.',
   );
   markFailed();

package/src/filedialog.js

@@ -2,13 +2,18 @@
 //
 // There is no one answer, so this is a ladder, tried in order:
 //
-//   1. **the portal** — `org.freedesktop.portal.FileChooser` over D-Bus. The
+//   1. **the native panel** — `NSOpenPanel`/`NSSavePanel` in this process, on
+//      the cocoa backend (src/cocoa/filepanels.js). A sheet on the window
+//      that asked, with every filter the OS type database knows. Found by
+//      the app the window belongs to offering `filePanels`, never by naming
+//      a backend here.
+//   2. **the portal** — `org.freedesktop.portal.FileChooser` over D-Bus. The
 //      real desktop dialog, with the user's bookmarks and recent files, drawn
 //      by GTK or KDE in another process. What a Linux desktop should get.
-//   2. **`osascript`** — macOS with no portal, which is every XQuartz install
-//      that has not gone out of its way. `choose file` is `NSOpenPanel`, so
-//      the user gets the dialog they know.
-//   3. **the built-in dialog** — a file browser drawn by react-x11 itself.
+//   3. **`osascript`** — macOS on the X11 backend with no portal, which is
+//      every XQuartz install that has not gone out of its way. `choose file`
+//      is `NSOpenPanel`, so the user gets the dialog they know.
+//   4. **the built-in dialog** — a file browser drawn by react-x11 itself.
 //      Reached over ssh, under a bare `startx`, in a container: everywhere
 //      there is a display and nothing else. See `components/FileDialog.js`;
 //      it needs a React tree, so `useFileDialog()` has it and the bare
@@ -24,12 +29,14 @@
 //   process; all you get is logical parenting, through `parent_window`. That
 //   is `transientFor` by another name, and it is why these calls want a window
 //   to point at.
-// - **macOS has no cross-process transient-for at all.** XQuartz windows are
-//   `NSWindow`s owned by X11.app, and `addChildWindow` is same-process only.
-//   So the panel appears over the app but is not attached to it. Application
-//   modality still works, because the caller is awaiting the promise.
+// - **`osascript` has no transient-for at all.** XQuartz windows are
+//   `NSWindow`s owned by X11.app, `addChildWindow` is same-process only, and
+//   the panel belongs to a third process anyway. So it appears over the app
+//   but is not attached to it. Application modality still works, because the
+//   caller is awaiting the promise. The native panel is the one rung on a
+//   Mac that *is* attached — a sheet — which is the whole reason it exists.
 // - **The built-in dialog is ours**, so it is the only rung that can be
-//   modal-and-parented properly — and the only one that has never seen the
+//   modal-and-parented on X11 — and the only one that has never seen the
 //   user's bookmarks.
 
 import {
@@ -45,7 +52,8 @@ import {
   variant,
 } from './portal.js';
 import { sessionBus } from './bus.js';
-import { windowIdOf } from './windowid.js';
+import { liveApps } from './trace-registry.js';
+import { windowIdOf, windowOf } from './windowid.js';
 
 const FILE_CHOOSER = 'org.freedesktop.portal.FileChooser';
 
@@ -60,9 +68,9 @@ const FILE_CHOOSER = 'org.freedesktop.portal.FileChooser';
 export class NoFileDialogError extends Error {
   constructor(cause) {
     super(
-      'react-x11: no file dialog is available — there is no ' +
-        'xdg-desktop-portal on the bus, and this is not macOS. Use ' +
-        'useFileDialog() instead, which draws one, or supply `backend`.',
+      'react-x11: no file dialog is available — no native panel on this ' +
+        'backend, no xdg-desktop-portal on the bus, and this is not macOS. ' +
+        'Use useFileDialog() instead, which draws one, or supply `backend`.',
       { cause },
     );
     this.name = 'NoFileDialogError';
@@ -230,14 +238,32 @@ async function osascriptDialog(kind, opts) {
           if (error.code === 'ENOENT') {
             return reject(new NoFileDialogError(error));
           }
+          // The caller's abort killed the child. From the outside that is a
+          // process that died on a signal, which is not a failure of the
+          // dialog: it is the abort, reported the way the portal rung
+          // reports one.
+          if (opts.signal?.aborted) {
+            return reject(
+              opts.signal.reason ??
+                new PortalCancelledError(RESPONSE_CANCELLED),
+            );
+          }
           // AppleScript reports a cancel as -128, which is an ordinary
           // outcome and must not read as a failure.
           if (/-128/.test(stderr) || /User canceled/i.test(stderr)) {
             return reject(new PortalCancelledError(RESPONSE_CANCELLED));
           }
+          // What osascript said, minus the lines AppKit prints to every
+          // process that puts a window up (IMKClient and friends), which
+          // would otherwise be the whole of the message.
+          const said = stderr
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line && !/\+\[IMK\w+ subclass\]/.test(line))
+            .join(' ');
           return reject(
             new Error(
-              `react-x11: the macOS file dialog failed — ${stderr.trim() || error.message}`,
+              `react-x11: the macOS file dialog failed — ${said || error.message}`,
               { cause: error },
             ),
           );
@@ -267,6 +293,29 @@ function defaultTitle(kind) {
       : 'Open file';
 }
 
+// --------------------------------------------------------------------------
+// Rung 1: the native panel, on the cocoa backend
+// --------------------------------------------------------------------------
+
+/**
+ * The app whose native panels a dialog should use, or null.
+ *
+ * Never a backend check: an app that can show panels says so by carrying
+ * `filePanels` (src/cocoa/app.js), and this asks the app the named window
+ * belongs to. With no window named it asks the connections the renderer is
+ * drawing through — one is the normal case; several with only one of them
+ * still showing a window is the next (a borrowed connection stays
+ * registered after its root unmounts); genuinely several is a real null,
+ * since a panel has to belong to one of them.
+ */
+function panelsApp(wnd) {
+  if (wnd) return wnd.app?.filePanels ? wnd.app : null;
+  const apps = liveApps().filter((app) => app.filePanels);
+  if (apps.length <= 1) return apps[0] ?? null;
+  const showing = apps.filter((app) => (app._rootChildren ?? []).length > 0);
+  return showing.length === 1 ? showing[0] : null;
+}
+
 /**
  * Which rung this machine lands on, without showing anything.
  *
@@ -274,9 +323,10 @@ function defaultTitle(kind) {
  * for the tests. It acquires a bus ref and releases it, so it is cheap to call
  * but not free — cache it if it is on a render path.
  *
- * @returns {Promise<'portal'|'osascript'|'builtin'>}
+ * @returns {Promise<'cocoa'|'portal'|'osascript'|'builtin'>}
  */
 export async function fileDialogBackend() {
+  if (panelsApp(null)) return 'cocoa';
   const ref = await sessionBus();
   if (ref) {
     try {
@@ -298,6 +348,21 @@ export async function fileDialogBackend() {
 export async function runNativeDialog(kind, opts = {}) {
   if (opts.backend === 'builtin') throw new NoFileDialogError();
 
+  const wantCocoa = !opts.backend || opts.backend === 'cocoa';
+  if (wantCocoa) {
+    const wnd = windowOf(opts.parentWindow);
+    const app = panelsApp(wnd);
+    if (app) return await app.filePanels.show(kind, opts, wnd);
+    if (opts.backend === 'cocoa') {
+      throw new NoFileDialogError(
+        new Error(
+          "backend: 'cocoa' — no native file panels here: the window is not " +
+            'on the cocoa backend, or the bridge is older than 0.5.',
+        ),
+      );
+    }
+  }
+
   const wantPortal = !opts.backend || opts.backend === 'portal';
   if (wantPortal) {
     const ref = await sessionBus();

package/src/index.d.ts

@@ -25,6 +25,10 @@ export * from './types/screencolor.js';
 export * from './types/appearance.js';
 export * from './types/fonts.js';
 export * from './types/system.js';
+export * from './types/launcher.js';
+export * from './types/tray.js';
+export * from './types/permissions.js';
+export * from './types/notifications.js';
 
 /**
  * The XID of the X11 window a ref points at, or `null` if there is not one
@@ -191,12 +195,24 @@ export interface RootOptions {
    * as the bridge reports it, 16 where the OS cannot say. A number here
    * applies to every window instead. `pumpInterval` is the AppKit event
    * pump's cadence, in ms (8 by default), which is the floor under input
-   * latency. Ignored off macOS and when {@link RootOptions.app} is passed.
+   * latency. `appName` is what the Dock, ⌘-Tab and the app menu print for
+   * an unbundled process (a bundle's Info.plist wins); `activationPolicy`
+   * is `'regular'` (a Dock tile, a ⌘-Tab entry — the default),
+   * `'accessory'` (a menu-bar app: windows but no tile) or `'prohibited'`,
+   * fixed before the app finishes launching. `exitOnQuit` (default `true`)
+   * ends the process once a quit request — the Dock's Quit, ⌘Q, a logout —
+   * has closed the app: the request routes through the primary window's
+   * close request first, so `onCloseRequest` there is where an app
+   * intercepts it; `false` is for an embedder that owns the process's
+   * lifetime. Ignored off macOS and when {@link RootOptions.app} is passed.
    */
   cocoa?: {
     presenter?: 'surface' | 'layers';
     frameInterval?: number;
     pumpInterval?: number;
+    appName?: string;
+    activationPolicy?: 'regular' | 'accessory' | 'prohibited';
+    exitOnQuit?: boolean;
   };
   /**
    * The size, in logical pixels, under which a `<text>` is painted as a

package/src/index.js

@@ -10,6 +10,23 @@ export {
   registerApplication,
 } from './application.js';
 export { useAppActivate, useAppOpen } from './apphooks.js';
+export { setBadge } from './launcher.js';
+export { useBadge, useDockMenu } from './launcherhooks.js';
+export { useTray } from './trayhooks.js';
+export {
+  NoPermissionServiceError,
+  openPrivacySettings,
+  permissionBackend,
+  permissionStatus,
+  requestPermission,
+} from './permissions.js';
+export { usePermission } from './permissionhooks.js';
+export {
+  NoNotificationServiceError,
+  notificationBackend,
+  notify,
+} from './notifications.js';
+export { useNotifier } from './notificationhooks.js';
 export { parseUriList } from './transfer.js';
 export { useApp, useClipboard, useSupports } from './appcontext.js';
 export { BusUnavailableError, closeBus, sessionBus, systemBus } from './bus.js';

package/src/launcher.js

@@ -0,0 +1,170 @@
+// The launcher's view of the app: the badge on its icon.
+//
+// A count on the Dock tile, a dot on the taskbar entry — the one thing an
+// app says to the desktop that the user reads without opening it. Two
+// desktops, two mechanisms, one call:
+//
+//   1. **the app's own tile** — the cocoa backend's `NSDockTile.badgeLabel`,
+//      reached through the app object (`setDockBadge`, src/cocoa/app.js).
+//      Any string shows, and it is the whole of the API on a Mac.
+//   2. **`com.canonical.Unity.LauncherEntry`** over the session bus — the
+//      protocol Unity defined and the KDE, elementary and Cairo-Dock
+//      launchers still listen for. One signal, `Update(app_uri, a{sv})`,
+//      carrying a `count` and whether it is visible, attributed to the app
+//      by `application://<id>.desktop` — which is why it needs the identity
+//      `registerApplication({ appId })` established: with no app id there is
+//      nothing for a launcher to pin the count to, and the call resolves
+//      false rather than guessing.
+//
+// The two disagree on what a badge *is*, and the API takes the stricter
+// shape: a **count**. A number shows on both; a string shows on macOS and is
+// a visible count of nothing on Linux (the protocol has no text field), so
+// pass a string only where the Mac is the audience. `0`, `null` and `''`
+// all clear it, because a badge of zero is the badge nobody wanted.
+//
+// Nothing here imports react: `useBadge` (launcherhooks.js) is the hook, and
+// this is the function under it, callable from host-side code with no tree.
+// The entry on the bus is held for as long as the badge is shown and
+// released when it is cleared — a held bus ref is a ref()'d socket, and an
+// app that cleared its badge on the way out should be free to exit.
+
+import { currentRegistration } from './application.js';
+import { loadTransport, sessionBus } from './bus.js';
+import { liveApps } from './trace-registry.js';
+
+export const LAUNCHER_ENTRY_IFACE = 'com.canonical.Unity.LauncherEntry';
+
+/**
+ * The object path libunity exports an entry at: a djb2 hash of the app URI
+ * under a fixed prefix. Launchers match on the signal's `app_uri` argument
+ * rather than the path, so any unique path would do — this one is the
+ * conventional one, and the tests read it to subscribe.
+ */
+export function launcherEntryPath(appUri) {
+  let hash = 5381;
+  for (const ch of String(appUri)) hash = (hash * 33 + ch.codePointAt(0)) >>> 0;
+  return `/com/canonical/unity/launcherentry/${hash}`;
+}
+
+/** `application://<appId>.desktop`, the URI the desktop knows an app by. */
+export function launcherAppUri(appId) {
+  return `application://${appId}.desktop`;
+}
+
+/**
+ * A badge value as the label a tile shows, or `null` for none: a number is
+ * its digits, a string is itself, and zero, empty, false and nothing are all
+ * "no badge".
+ */
+export function badgeLabel(value) {
+  if (value == null || value === false || value === '') return null;
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value !== 0
+      ? String(Math.trunc(value))
+      : null;
+  }
+  return String(value);
+}
+
+/** The app to badge when the caller did not say: the one connection the
+ *  renderer draws through, or the one of several still showing a window. */
+function soleApp() {
+  const apps = liveApps();
+  if (apps.length <= 1) return apps[0] ?? null;
+  const showing = apps.filter((app) => (app._rootChildren ?? []).length > 0);
+  return showing.length === 1 ? showing[0] : null;
+}
+
+/** The one exported entry per process — an app has one icon. */
+let entry = null;
+
+async function launcherEntry(appUri) {
+  if (entry && entry.appUri === appUri) return entry;
+  if (entry) await releaseEntry();
+  const ref = await sessionBus();
+  if (!ref) return null;
+  let dbus;
+  try {
+    dbus = await loadTransport();
+  } catch {
+    await ref.release();
+    return null;
+  }
+  const iface = dbus.defineInterface({
+    name: LAUNCHER_ENTRY_IFACE,
+    methods: {},
+    signals: {
+      Update: { args: { app_uri: 's', properties: 'a{sv}' } },
+    },
+  });
+  let registration;
+  try {
+    registration = await ref.bus.export(launcherEntryPath(appUri), iface);
+  } catch {
+    await ref.release();
+    return null;
+  }
+  entry = { appUri, ref, dbus, iface, registration };
+  return entry;
+}
+
+async function releaseEntry() {
+  const held = entry;
+  entry = null;
+  if (!held) return;
+  await held.registration?.remove?.().catch(() => {});
+  await held.ref.release();
+}
+
+/**
+ * Show `value` on the app's icon, or clear it.
+ *
+ * ```js
+ * await setBadge(unread);        // 3 → "3"; 0 → cleared
+ * await setBadge(null);          // cleared
+ * ```
+ *
+ * Resolves to whether a launcher was told: `false` means there is nothing
+ * on this machine to show a badge — no cocoa Dock tile, and no session bus
+ * or no `registerApplication({ appId })` for the Linux protocol to attribute
+ * it to. Never rejects for anything about the machine: a badge is not a
+ * thing an app should have an error path for.
+ *
+ * `app` names the connection when there are several; the one the renderer
+ * draws through is the default.
+ */
+export async function setBadge(value, { app } = {}) {
+  const label = badgeLabel(value);
+  const target = app ?? soleApp();
+
+  // Rung 1: the app's own tile.
+  if (typeof target?.setDockBadge === 'function') {
+    target.setDockBadge(label);
+    return true;
+  }
+
+  // Rung 2: the launcher protocol, which needs an identity to badge.
+  const appId = currentRegistration()?.appId;
+  if (!appId) {
+    if (label === null) await releaseEntry();
+    return false;
+  }
+  const appUri = launcherAppUri(appId);
+  if (label === null && !entry) return false; // nothing shown, nothing to clear
+  const held = await launcherEntry(appUri);
+  if (!held) return false;
+  const count =
+    typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : 0;
+  const V = held.dbus.Variant;
+  held.iface.emit.Update(appUri, {
+    count: new V('x', label === null ? 0 : count),
+    'count-visible': new V('b', label !== null),
+  });
+  if (label === null) await releaseEntry();
+  return true;
+}
+
+/** Test seam, not public: drop the exported entry without emitting. */
+export async function _resetLauncher() {
+  await releaseEntry();
+}

package/src/launcherhooks.js

@@ -0,0 +1,81 @@
+// `useBadge()` and `useDockMenu()` — the launcher's view of the app, as
+// things a component declares rather than manages.
+//
+// The badge lives in `launcher.js` and is cross-backend; the Dock menu is
+// the cocoa backend's alone, because its freedesktop counterpart — desktop
+// actions in the `.desktop` file — is an install step and not runtime code.
+// Where a hook has no mechanism it is inert, with a one-time development
+// note naming the backend: the inert-props policy of docs/macos.md, so
+// shared app code stays branch-free.
+
+import { useEffect, useRef } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+import { setBadge } from './launcher.js';
+
+/**
+ * Show `value` on the app's icon while this component is mounted, and clear
+ * it on unmount.
+ *
+ * ```jsx
+ * useBadge(unread); // a count; 0 clears
+ * ```
+ *
+ * A number shows on both backends; a string shows on macOS only — see
+ * docs/desktop.md. Nothing is shown where nothing can show it, silently: a
+ * badge is not a feature an app should branch on.
+ */
+export function useBadge(value) {
+  const app = useAppOrNull();
+  useEffect(() => {
+    setBadge(value, { app }).catch(() => {});
+  }, [value, app]);
+  useEffect(() => {
+    return () => {
+      setBadge(null, { app }).catch(() => {});
+    };
+  }, [app]);
+}
+
+let warnedInert = false;
+
+/**
+ * The menu behind a right-click on the Dock icon, from the same `items`
+ * vocabulary `MenuBar` and `ContextMenu` take — an item's `onSelect` fires
+ * when the user picks it.
+ *
+ * ```jsx
+ * useDockMenu([
+ *   { label: 'New Window', onSelect: openWindow },
+ *   { type: 'separator' },
+ *   { label: 'Recent', items: recent.map(toItem) },
+ * ]);
+ * ```
+ *
+ * Installed for as long as the component is mounted, replaced when `items`
+ * changes, and taken down on unmount. Inert off the cocoa backend, with a
+ * development note the first time.
+ */
+export function useDockMenu(items) {
+  const app = useAppOrNull();
+  // read at activation time, so a pick three minutes from now runs the
+  // handler from the current render rather than the mounting one
+  const live = useRef(items);
+  live.current = items;
+
+  useEffect(() => {
+    if (typeof app?.setDockMenu !== 'function') {
+      if (process.env.NODE_ENV !== 'production' && !warnedInert && app) {
+        warnedInert = true;
+        console.warn(
+          'react-x11: useDockMenu() is inert on this backend — only the ' +
+            'cocoa backend has a Dock. On a Linux desktop the counterpart ' +
+            'is desktop actions in the .desktop file (docs/desktop.md).',
+        );
+      }
+      return undefined;
+    }
+    app.setDockMenu(items ?? null);
+    return () => app.setDockMenu(null);
+  }, [items, app]);
+}