react-x11 2.6.1 → 2.8.0

package/src/dnd.js

@@ -258,6 +258,13 @@ export class DropSession {
     // FIFO gate: messages queue behind atom interning and XdndEnter's
     // async type-list resolution, so a Position never overtakes its Enter.
     this._chain = Promise.resolve();
+    // The lane an enter/over dispatch schedules its renders in. Continuous
+    // by default, because a drag hovering is a stream like the pointer's
+    // own and the frame clock paces it. A transport whose backend *stops*
+    // that clock for the duration of the drag raises it — the cocoa one
+    // does (src/cocoa/dnd.js), because inside AppKit's tracking loop a
+    // render scheduled for the next frame lands after the drop.
+    this.hoverPriority = ContinuousEventPriority;
     this._reset();
   }
 
@@ -269,6 +276,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';
@@ -467,7 +477,7 @@ export class DropSession {
       action: this.requestedAction,
       freeze: false,
     };
-    runWithPriority(ContinuousEventPriority, () => {
+    runWithPriority(this.hoverPriority, () => {
       this._updateDragPath(path, native);
       // onDragOver may override the declarative answer, synchronously —
       // same latency budget as any event handler, no render awaited
@@ -491,7 +501,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 +516,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 +529,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 +572,7 @@ export class DropSession {
     })();
     this.accepted = null;
     this.lastPoint = null;
+    this._viaLocal = false;
     this._source = 'external';
     return {
       handled: outcome.accept,
@@ -1186,6 +1204,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 +1238,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);
@@ -1245,13 +1265,33 @@ export class DragSession {
       Array.isArray(actions) && actions.length > 0 ? actions : ['copy'];
     this.currentAction = this.actions[0];
     this._resolved = new Map();
-    const ev = this.node.events.dispatch('DragStart', source, native, {
-      types: this.types,
-      action: this.currentAction,
-      source: 'internal',
-      screenX: (native.rootx ?? native.x) / this.node.events.scale,
-      screenY: (native.rooty ?? native.y) / this.node.events.scale,
-    });
+    // 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;
+    const nativeSession = typeof wnd?.beginDrag === 'function';
+    // …and it owns the thread for the *whole* gesture, so anything this
+    // dispatch schedules for later has no later: the `<popup dragPreview>`
+    // an `onDragStart` setState renders would otherwise be created after
+    // the drop. Discrete priority puts the update in the one lane a
+    // backend can land by hand from inside a callback (`flushSyncWork`,
+    // src/cocoa/app.js `_afterInput`). Where the frame clock keeps running,
+    // the motion this arrived on is paced like any other and the update
+    // keeps the priority the dispatcher gave it.
+    const startEvent = () =>
+      this.node.events.dispatch('DragStart', source, native, {
+        types: this.types,
+        action: this.currentAction,
+        source: 'internal',
+        screenX: (native.rootx ?? native.x) / this.node.events.scale,
+        screenY: (native.rooty ?? native.y) / this.node.events.scale,
+      });
+    const ev = nativeSession
+      ? runWithPriority(DiscreteEventPriority, startEvent)
+      : startEvent();
     if (ev.defaultPrevented) {
       this._reset();
       return false;
@@ -1259,9 +1299,94 @@ export class DragSession {
     this.phase = 'dragging';
     source.setStyleState(':dragging', true);
     this._setCursor('grab');
+    if (nativeSession) {
+      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.
+   *
+   * Discrete priority, like the start: this is the only news of the gesture
+   * that arrives while the native session owns the thread, so the render it
+   * schedules has to be landable from inside the callback. A preview that
+   * follows the pointer is exactly a render per position. */
+  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) {
+      runWithPriority(DiscreteEventPriority, () =>
+        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;
+    // the release, and the last callback before the thread comes back:
+    // `onDragEnd` takes the preview down, and that is a discrete answer to
+    // the button like any other
+    runWithPriority(DiscreteEventPriority, () =>
+      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 +1479,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
@@ -184,19 +188,42 @@ export interface RootOptions {
    * The Cocoa backend's knobs (docs/macos.md). `presenter` picks the frame
    * path: `'surface'` (the measured default — one bitmap per window, the
    * X11 paint machinery over an IOSurface swapchain) or `'layers'` (one
-   * CALayer per drawn node, opt-in while it is measured).
+   * CALayer per drawn node, opt-in while it is measured). `promote` is the
+   * surface presenter's layer promotion: a plain `<box>` with a transition
+   * or a loop on its colour, border or radius gets a CALayer of its own
+   * above the bitmap for as long as it animates, and the render server
+   * draws the motion — no frames, and it keeps moving while the JS thread
+   * is busy. On by default where the bridge draws a layer's colour and a
+   * rastered one alike (`@windowkit/appkit` >= 0.5.1, which says so with
+   * `colorSpace()`; off on 0.5.0, where the two shades differed); `true`
+   * turns it on regardless, `false` keeps every animation on the frame
+   * clock.
+   * `REACT_X11_COCOA_PROMOTE=1` / `=0` say the same from the environment.
    * `frameInterval` is how often a scheduled frame may paint, in ms. By
    * default each window paces itself on the display it is on — 8.3ms on
    * a 120Hz panel, 16.7 on a 60Hz monitor, the screen's own refresh rate
    * 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';
+    promote?: boolean;
     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();
+}