react-x11 2.16.0 → 2.17.0

package/src/nodes/window/hints.js

@@ -232,6 +232,23 @@ export function windowAttributes(props, scale = 1) {
         : props[key];
   }
   if (Object.keys(hints).length > 0) attributes.sizeHints = hints;
+  // The desktop identity of this window, under the one name every desktop's
+  // own word maps onto: `WM_CLASS` on X11, `app_id` on Wayland,
+  // AppUserModelID on Windows. `wmClass` was X11's word for it and is still
+  // accepted, so both are normalised here and a backend reads one key.
+  //
+  // X11 carries a *pair* — an instance naming this window and a class naming
+  // the application — and everything since carries one string. The class is
+  // the application's, so the class is what a single-id backend is given; the
+  // pair itself still reaches `setClass` from the props (`applyWindowHints`).
+  const identity = attributes.appId ?? attributes.wmClass;
+  if (identity !== undefined) {
+    attributes.appId = Array.isArray(identity)
+      ? (identity[1] ?? identity[0])
+      : identity && typeof identity === 'object'
+        ? (identity.class ?? identity.instance)
+        : identity;
+  }
   if (props.style !== undefined) {
     const style = flattenStyle(props.style);
     if (style.backgroundColor !== undefined) {
@@ -325,8 +342,10 @@ export class WindowHints {
         this._sendSizeHints(next);
       }
     }
-    if (!shallowEqual(next.wmClass, prev.wmClass) && next.wmClass) {
-      const c = next.wmClass;
+    const identity = next.appId ?? next.wmClass;
+    const wasIdentity = prev.appId ?? prev.wmClass;
+    if (!shallowEqual(identity, wasIdentity) && identity) {
+      const c = identity;
       if (Array.isArray(c)) wnd.setClass?.(c[0], c[1]);
       else if (typeof c === 'object') wnd.setClass?.(c.instance, c.class);
       else wnd.setClass?.(c);

package/src/nodes/window/window.js

@@ -138,8 +138,8 @@ export function flushWindowRestacks() {
  * issue #4).
  */
 export class WindowNode extends Scrollable(Node) {
-  constructor(app, attributes, props) {
-    super('window', props, app, { yoga: true });
+  constructor(app, attributes, props, { awaitsRootScope = false } = {}) {
+    super('window', props, app, { yoga: true, awaitsRootScope });
     assertWindowSize(props, this.kind);
     this.root = this;
     this.attributes = attributes;

package/src/notifications.js

@@ -429,6 +429,19 @@ function centreFor(options) {
   return app?.notifications ?? null;
 }
 
+/**
+ * Which rung a backend's own notification centre is.
+ *
+ * The seam is the backend's, not macOS's: a centre answers `available()` and
+ * `post()`, and the cocoa one was simply the first. `kind` is how a centre
+ * says which rung it is, so `notificationBackend()` reports the truth rather
+ * than the name of whoever got here first. Cocoa's predates the field and is
+ * the default.
+ */
+function kindOf(centre) {
+  return centre?.kind ?? 'cocoa';
+}
+
 /**
  * Which rung this machine lands on, without posting anything.
  *
@@ -442,10 +455,11 @@ function centreFor(options) {
 export async function notificationBackend(options = {}) {
   const backend = options.backend;
   const want = (rung) => !backend || backend === rung;
-  if (want('cocoa')) {
-    const centre = centreFor(options);
-    if (centre && (await centre.available())) return 'cocoa';
-    if (backend === 'cocoa') return null;
+  const centre = centreFor(options);
+  const kind = kindOf(centre);
+  if (want(kind)) {
+    if (centre && (await centre.available())) return kind;
+    if (backend === kind) return null;
   }
   if (want('dbus')) {
     const ref = await sessionBus();
@@ -461,7 +475,14 @@ export async function notificationBackend(options = {}) {
   if (want('osascript') && (process.platform === 'darwin' || backend)) {
     return 'osascript';
   }
-  if (want('notify-send') && (process.platform !== 'darwin' || backend)) {
+  // `notify-send` is a freedesktop tool. Windows has neither it nor a shell
+  // command that shows a notification, so the rung above is the floor there
+  // and `null` is the honest answer when the tree is not on the win32
+  // backend — a spawn that would fail with ENOENT is not a rung.
+  if (
+    want('notify-send') &&
+    (backend || (process.platform !== 'darwin' && process.platform !== 'win32'))
+  ) {
     return 'notify-send';
   }
   return null;
@@ -497,26 +518,28 @@ export async function notify(options = {}) {
   const backend = options.backend;
   const want = (rung) => !backend || backend === rung;
 
-  if (want('cocoa')) {
-    const centre = centreFor(options);
+  const centre = centreFor(options);
+  const kind = kindOf(centre);
+  if (want(kind)) {
     if (centre && (await centre.available())) {
       const handle = await centre.post(options);
       if (handle) return handle;
       // The bundle is right and the centre is there, but the system never
       // put the prompt in front of anybody, so nobody declined: not the
       // refusal above, and no reason to stop. The ladder moves on.
-      if (backend === 'cocoa') {
+      if (backend === kind) {
         throw new NoNotificationServiceError(
-          "backend: 'cocoa' — the centre could not ask for authorization " +
+          `backend: '${kind}' — the centre could not ask for authorization ` +
             '(the status is still notDetermined). A bundle macOS has not ' +
             'registered never gets the prompt (docs/notifications.md).',
         );
       }
-    } else if (backend === 'cocoa') {
+    } else if (backend === kind) {
       throw new NoNotificationServiceError(
-        "backend: 'cocoa' — no notification centre here: the tree is not " +
-          'on the cocoa backend, the bridge is older than 0.5, or this ' +
-          'process is not an app bundle (docs/notifications.md).',
+        `backend: '${kind}' — no notification centre here: the tree is not ` +
+          'on a backend that has one, the bridge is older than the version ' +
+          'that added it, or on macOS this process is not an app bundle ' +
+          '(docs/notifications.md).',
       );
     }
   }
@@ -534,7 +557,9 @@ export async function notify(options = {}) {
   const shell =
     want('osascript') && (process.platform === 'darwin' || backend)
       ? 'osascript'
-      : want('notify-send') && (process.platform !== 'darwin' || backend)
+      : want('notify-send') &&
+          (backend ||
+            (process.platform !== 'darwin' && process.platform !== 'win32'))
         ? 'notify-send'
         : null;
   if (shell) {

package/src/screens.js

@@ -119,6 +119,11 @@ class ScreenSession {
     this._desktopAtom = null;
     this._snapshot = null;
     this._listeners = new Set();
+    /** A backend that has to be *asked* for its layout rather than told —
+     *  see `setScreenPolling`. `_revalidate` re-reads it now; `_watched` is
+     *  told whether anything is subscribed. */
+    this._revalidate = null;
+    this._watched = null;
     /** Every `X.on('event')` handler installed here, so `stop()` can take
      *  them off again rather than leaving one per root on a shared client. */
     this._handlers = [];
@@ -138,7 +143,11 @@ class ScreenSession {
       }
     }
     this._handlers.length = 0;
+    const watched = this._listeners.size > 0;
     this._listeners.clear();
+    if (watched) this._watch(false);
+    this._revalidate = null;
+    this._watched = null;
   }
 
   /** Install an X event handler that this session owns. */
@@ -183,32 +192,35 @@ class ScreenSession {
 
   subscribe(fn) {
     this._listeners.add(fn);
-    return () => this._listeners.delete(fn);
+    if (this._listeners.size === 1) this._watch(true);
+    return () => {
+      if (!this._listeners.delete(fn)) return;
+      if (!this._listeners.size) this._watch(false);
+    };
   }
-}
 
-/** The monitor a point is on, or the largest one when it is on none (a
- *  window whose owner the WM has not placed yet, or coordinates from a
- *  screen layout that has since changed). */
-function monitorAt(monitors, point) {
-  if (!monitors?.length) return null;
-  if (point) {
-    for (const m of monitors) {
-      if (
-        point.x >= m.x &&
-        point.x < m.x + m.width &&
-        point.y >= m.y &&
-        point.y < m.y + m.height
-      ) {
-        return m;
-      }
+  /** Ask a pulled backend to re-read the layout, now. Synchronous: the
+   *  callers are placement paths with no round trip available to them. */
+  revalidate() {
+    if (!this._revalidate || this.stopped) return;
+    try {
+      this._revalidate();
+    } catch {
+      // a backend that cannot answer leaves the layout it published
+      // standing, which is a better answer than none
     }
   }
-  let best = monitors[0];
-  for (const m of monitors) {
-    if (m.width * m.height > best.width * best.height) best = m;
+
+  /** Whether anything is subscribed, for a backend that only has to keep
+   *  asking while someone is listening. */
+  _watch(on) {
+    if (!this._watched) return;
+    try {
+      this._watched(on);
+    } catch {
+      // as above: its clock, its problem
+    }
   }
-  return best;
 }
 
 /** The overlap of two rects, or `null` where they do not touch. */
@@ -221,6 +233,82 @@ function intersect(a, b) {
   return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
 }
 
+/** How far apart two rects are, squared: zero where they meet, and the gap
+ *  between their nearest edges otherwise. Squared because nothing compares
+ *  it against a length — only against another of these. */
+function gapSquared(a, b) {
+  const dx = Math.max(a.x - (b.x + b.width), b.x - (a.x + a.width), 0);
+  const dy = Math.max(a.y - (b.y + b.height), b.y - (a.y + a.height), 0);
+  return dx * dx + dy * dy;
+}
+
+/** The biggest monitor there is — the stand-in for "the one you look at",
+ *  for a question with no position in it at all. */
+function largestMonitor(monitors) {
+  let best = monitors[0];
+  for (const m of monitors) {
+    if (m.width * m.height > best.width * best.height) best = m;
+  }
+  return best;
+}
+
+/**
+ * The monitor `near` is on. `near` is a rect in screen coordinates, and a
+ * point is the 1x1 rect at it — the same containment a point used to get,
+ * since a 1x1 rect overlaps exactly the monitor that contains its corner.
+ *
+ * **The one it overlaps most**, because one corner of a rect does not say
+ * which monitor the rect is on. A menu-bar item's frame starts a few points
+ * *above* the top of its own display, and on a desk where another display
+ * reaches down past that edge, the corner alone is inside the *other*
+ * monitor — or inside none — and the popup opens there (#618). Every rect
+ * that has a size knows better than its corner does.
+ *
+ * **The nearest one**, by the gap between the rects, when it overlaps none.
+ * A rect that is off every monitor is nearly always just outside one of
+ * them — that same menu-bar furniture, a pointer at the very edge, a window
+ * the WM has not placed yet — and the nearest monitor is the only answer
+ * that has anything to do with where it was. The largest was the old answer
+ * and it can be anywhere on the desk.
+ *
+ * With no position at all (`near` null — an auto-sized window with no owner
+ * to open beside), the largest monitor, which is all there is to go on.
+ */
+function monitorAt(monitors, near) {
+  if (!monitors?.length) return null;
+  if (!near) return largestMonitor(monitors);
+  // A degenerate rect counts as its own thinnest real version, the way
+  // `anchorOffscreen` reads a caret: a point is 1x1, and so is a rect whose
+  // size nobody filled in.
+  const rect = {
+    x: near.x,
+    y: near.y,
+    width: near.width > 1 ? near.width : 1,
+    height: near.height > 1 ? near.height : 1,
+  };
+  let best = null;
+  let most = 0;
+  for (const m of monitors) {
+    const over = intersect(m, rect);
+    const area = over ? over.width * over.height : 0;
+    if (area > most) {
+      best = m;
+      most = area;
+    }
+  }
+  if (best) return best;
+  let nearest = monitors[0];
+  let least = Infinity;
+  for (const m of monitors) {
+    const gap = gapSquared(m, rect);
+    if (gap < least) {
+      nearest = m;
+      least = gap;
+    }
+  }
+  return nearest;
+}
+
 /**
  * The usable part of one monitor.
  *
@@ -262,12 +350,19 @@ function usable(monitor, work) {
 
 /**
  * The rect an auto-sized window may grow into, or `null` where there is
- * nothing to ask. `near` is a screen-coordinate point the window will open
- * next to — a `transientFor` owner's origin, in practice — and picks the
- * monitor when there are several.
+ * nothing to ask. `near` is a screen-coordinate **rect** the window will
+ * open against — a `transientFor` owner's origin, the node a popup hangs
+ * off, the tray item a click reported — and picks the monitor when there
+ * are several (`monitorAt`); `{x, y}` alone is a point.
  */
 export function availableArea(app, near = null) {
   const session = sessions.get(app);
+  // The monitor a popup is flipped and clamped into is picked here, so a
+  // backend whose layout is pulled rather than pushed is asked *now*
+  // rather than answered from whatever it last read (`setScreenPolling`).
+  // A rect the desk has since moved lands inside another monitor's stale
+  // one, and the popup opens at that monitor's edge (#617).
+  session?.revalidate();
   const screen = session?.screenRect ?? null;
   if (!session) return screen;
   const monitor = monitorAt(session.monitors, near) ?? screen;
@@ -364,6 +459,46 @@ export function watchScreens(app, fn) {
   return session.subscribe(fn);
 }
 
+/**
+ * Register a backend whose layout has to be **pulled**.
+ *
+ * X11 and Wayland are told: RandR sends an event, a `wl_output` announces
+ * itself, and a `publish` lands from the handler. The cocoa bridge keeps
+ * its `NSScreen` copy current on macOS's own
+ * `NSApplicationDidChangeScreenParametersNotification` but emits no event
+ * for it, so there a display plugged in, rearranged or made primary is a
+ * question nobody asked (#617). This is where the asking is wired up:
+ *
+ * - `revalidate()` re-reads the layout and publishes any change. Called
+ *   before `availableArea()` picks the monitor a window is sized against
+ *   or a popup is clamped into, which is where a stale rect does visible
+ *   damage, and synchronous for that reason.
+ * - `watched(on)` is told when the *first* subscriber arrives and when the
+ *   last one leaves. A change nobody asked about still has to reach
+ *   `useScreens()`, which needs a clock where there is no event — and a
+ *   clock that only runs while a component is watching costs an app that
+ *   never asks nothing at all.
+ *
+ * Both are optional, and a session with neither behaves exactly as it did:
+ * this adds no work to the X11 path.
+ */
+export function setScreenPolling(
+  app,
+  { revalidate = null, watched = null } = {},
+) {
+  let session = sessions.get(app);
+  if (!session) {
+    session = new ScreenSession(app);
+    sessions.set(app, session);
+  }
+  session._revalidate = revalidate;
+  session._watched = watched;
+  // Registered after a `useScreens()` already mounted — the backend still
+  // has to hear that it is being watched.
+  if (watched && session._listeners.size) session._watch(true);
+  return session;
+}
+
 // --------------------------------------------------------------------------
 // Starting up
 // --------------------------------------------------------------------------

package/src/taskbarhooks.js

@@ -0,0 +1,164 @@
+// The Windows taskbar's own surfaces, as hooks.
+//
+// Three things the taskbar has that no other desktop does, so none of them is
+// a rung on an existing ladder and none of them pretends to be portable. What
+// makes them safe to use anyway is that the answer to "is this here" is a
+// value a component branches on rather than a platform check, and the hooks
+// below do nothing at all where the backend has not installed them. An app
+// writes the same tree everywhere and gets the feature where it exists.
+//
+// ```jsx
+// const launcher = useDesktopCapability('launcher');
+// useThumbnailToolbar(
+//   launcher.features.thumbnailToolbar ? [
+//     { id: 'prev', tooltip: 'Previous', icon: prevIcon },
+//     { id: 'play', tooltip: playing ? 'Pause' : 'Play', icon: playIcon },
+//   ] : null,
+//   (id) => transport(id),
+// );
+// ```
+//
+// They are **features of the launcher** — the same rung as the badge and the
+// progress bar, since all of them hang off the one icon the desktop shows for
+// this app — and not entries in `useSupports()`, which answers for the
+// display. The seam is one rule: the backend installs a method, and its
+// presence is the capability; the probe in `src/capabilities.js` reads those
+// same methods, so the prediction and the hook cannot disagree. Nothing here
+// knows what Windows is, and neither does anything in an app that uses it.
+import { useEffect, useRef } from 'react';
+
+import { useAppOrNull } from './appcontext.js';
+import { liveApps } from './trace-registry.js';
+import { useTopLevelWindow } from './windowid.js';
+
+/** The app to act on when the caller did not say — the same rule the
+ *  launcher's own imperative calls use. */
+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 value a caller passed, read by an effect that must not re-run for it. */
+function useLatest(value) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+/** A stable key for a button list, so an effect re-runs when one actually
+ *  changed rather than on every render. Icons compare by identity — a caller
+ *  holding its icons still is the fast path, and one that rebuilds them every
+ *  render was going to re-upload them anyway. */
+function signatureOf(buttons) {
+  if (!buttons) return '';
+  return buttons
+    .map(
+      (b) =>
+        `${b.id ?? ''}\u0000${b.tooltip ?? b.label ?? ''}\u0000` +
+        `${b.enabled === false ? 0 : 1}${b.dismissOnClick ? 1 : 0}`,
+    )
+    .join('\u0001');
+}
+
+/**
+ * Up to seven buttons under this window's taskbar hover preview — where a
+ * media player puts play and skip.
+ *
+ * `buttons` is `[{ id, tooltip, icon, enabled, dismissOnClick }]`, and `icon`
+ * is whatever `useTray` takes: an ntk `Image`, raw RGBA with a size, or a
+ * path. `null` takes the toolbar down as far as the shell allows, which is to
+ * hide the buttons — a toolbar cannot be removed once the window has one, and
+ * saying so is better than a call that looks like it worked.
+ *
+ * `onClick` is called with the button's own `id`.
+ *
+ * Does nothing where the backend has no toolbar. The eighth button and beyond
+ * are dropped rather than refused, because the shell refuses the whole call
+ * for an eighth and one silently missing button is a better outcome than a
+ * toolbar that never appears.
+ */
+export function useThumbnailToolbar(buttons, onClick) {
+  const app = useAppOrNull();
+  const owner = useTopLevelWindow();
+  const handler = useLatest(onClick);
+  const latest = useLatest(buttons);
+  const signature = signatureOf(buttons);
+
+  useEffect(() => {
+    if (typeof app?.thumbnailToolbar !== 'function') return;
+    // Read inside the effect: `useTopLevelWindow` answers through a getter,
+    // so the window a tree is in is whatever it is when the effect runs
+    // rather than what it was at render.
+    const wnd = owner?.current?.window;
+    if (!wnd?.id) return;
+    app.thumbnailToolbar(wnd.id, latest.current ?? []);
+
+    const fire = (event) => handler.current?.(event.id, event);
+    wnd.on?.('thumbbutton', fire);
+    return () => {
+      wnd.off?.('thumbbutton', fire);
+      // Hidden rather than removed, which is all the shell offers.
+      app.thumbnailToolbar(wnd.id, []);
+    };
+    // `signature` is the dependency; the buttons themselves are read through
+    // a ref, so a new array holding the same buttons does not re-send them.
+  }, [app, owner, signature, latest, handler]);
+}
+
+/**
+ * The Tasks category of this application's jump list — the menu on a right
+ * click of its taskbar button.
+ *
+ * `tasks` is `[{ title, arguments, description }]`. Each one **relaunches
+ * this executable** with the arguments given, which is what a jump-list task
+ * is: the shell starts the program, it does not call back into the running
+ * one. An app that wants the running instance to answer needs the single
+ * instance path, which is not built (docs/windows-integrations.md) — so until
+ * then a task is for something the app can do from a cold start.
+ *
+ * `null` deletes the category.
+ */
+export function useJumpList(tasks) {
+  const app = useAppOrNull();
+  const latest = useLatest(tasks);
+  // The tasks are plain data — a title, arguments, a description — so their
+  // own JSON is the dependency, and a caller rebuilding an equal array every
+  // render does not re-send it. Read through a ref for the same reason
+  // `useThumbnailToolbar` does: the value is what it is when the effect runs.
+  const signature = JSON.stringify(tasks ?? null);
+
+  useEffect(() => {
+    if (typeof app?.jumpList !== 'function') return;
+    app.jumpList(latest.current ?? []);
+    return () => app.jumpList([]);
+  }, [app, signature, latest]);
+}
+
+/**
+ * Note a document this app just opened, for the shell's Recent lists — the
+ * jump list's own Recent section, and Explorer's quick access.
+ *
+ * The same act as macOS's `noteNewRecentDocumentURL:`; it lives here rather
+ * than in a cross-platform hook because this is the only backend with one to
+ * call today. Where the file type is not associated with this application the
+ * shell may keep it and show it nowhere, which is its decision to make.
+ *
+ * `null` clears the list.
+ */
+export function noteRecentDocument(path, { app } = {}) {
+  const target = app ?? soleApp();
+  if (typeof target?.noteRecentDocument !== 'function') return false;
+  target.noteRecentDocument(path);
+  return true;
+}
+
+/** The hook form: notes `path` whenever it changes. */
+export function useRecentDocument(path) {
+  const app = useAppOrNull();
+  useEffect(() => {
+    if (typeof app?.noteRecentDocument !== 'function' || path == null) return;
+    app.noteRecentDocument(path);
+  }, [app, path]);
+}

package/src/transfer.js

@@ -70,6 +70,25 @@ export function decodeData(data, target) {
  * URIs that are actually local — a remote `file://host/...` has no local
  * path and must not pretend to.
  */
+/**
+ * A `file:` URL's pathname as a path this machine can open.
+ *
+ * On a POSIX path the two are the same string. A Windows one is not: the URL
+ * form of `C:\Users\a` is `file:///C:/Users/a`, whose pathname is
+ * `/C:/Users/a` — a leading slash that no Windows API accepts, and forward
+ * slashes that most of them tolerate and no user recognises. A drive letter
+ * after the slash is the tell, and it is unambiguous: no POSIX path begins
+ * `/C:`.
+ *
+ * Decided by the shape of the path rather than by `process.platform`, so a
+ * uri-list that arrived from another machine reads the same way on both.
+ */
+function pathOfFileUrl(pathname) {
+  const drive = /^\/([A-Za-z]:)(\/.*)?$/.exec(pathname);
+  if (!drive) return pathname;
+  return (drive[1] + (drive[2] ?? '\\')).replace(/\//g, '\\');
+}
+
 export function parseUriList(text) {
   const files = [];
   for (const line of String(text).split(/\r?\n/)) {
@@ -82,7 +101,7 @@ export function parseUriList(text) {
         url.protocol === 'file:' &&
         (url.hostname === '' || url.hostname === 'localhost')
       ) {
-        entry.path = decodeURIComponent(url.pathname);
+        entry.path = pathOfFileUrl(decodeURIComponent(url.pathname));
       }
     } catch {
       // not a parseable URI — keep the raw line, claim no path

package/src/trayhooks.js

@@ -73,7 +73,7 @@ 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,
+ * `useLauncherMenu` take, an item's `onSelect` firing when picked. Without one,
  * `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

package/src/types/capabilities.d.ts

@@ -10,7 +10,13 @@ export type DesktopBackend =
   | 'osascript'
   | 'notify-send'
   | 'statusnotifier'
-  | 'launcherentry';
+  | 'launcherentry'
+  /** A Shell_NotifyIcon balloon. */
+  | 'win32'
+  /** The notify icon itself, as a tray. */
+  | 'shellnotifyicon'
+  /** `ITaskbarList3` and the jump list, as a launcher. */
+  | 'taskbar';
 
 /** The capabilities {@link desktopCapability} can be asked about. */
 export type DesktopCapabilityName = 'notifications' | 'tray' | 'launcher';
@@ -60,14 +66,37 @@ export interface TrayFeatures {
 
 export interface LauncherFeatures {
   badge: boolean;
-  /** A string badge. macOS only — the launcher protocol carries a count. */
+  /**
+   * A string badge rather than a count. False on the launcher protocol,
+   * which carries a number; the taskbar draws the text into its overlay
+   * icon, where about three glyphs fit before it becomes `99+`.
+   */
   badgeText: boolean;
   progress: boolean;
   urgent: boolean;
-  /** The Dock menu / quicklist. */
+  /**
+   * The Dock menu / quicklist: entries that **call back into this process**.
+   * False on the taskbar, whose menu is the jump list — see `tasks`.
+   */
   menu: boolean;
   /** The launcher needs an installed `.desktop` file to attach this to. */
   needsDesktopFile: boolean;
+  /**
+   * Static entries on the icon's menu that start a **new process** with
+   * arguments, rather than calling back into this one: the jump list's Tasks
+   * category. A different feature from `menu`, and `useJumpList` drives it.
+   */
+  tasks: boolean;
+  /**
+   * Buttons under the icon's hover preview, which `useThumbnailToolbar`
+   * drives. The taskbar's alone.
+   */
+  thumbnailToolbar: boolean;
+  /**
+   * The launcher keeps a Recent list this app can add to, through
+   * `useRecentDocument`.
+   */
+  recentDocuments: boolean;
 }
 
 export interface DesktopCapabilityResult<F = Record<string, boolean>> {