react-x11 2.16.1 → 2.17.1

package/src/index.js

@@ -4,7 +4,13 @@ import './bootstrap.js';
 
 export { createRoot, Renderer } from './Reconciler.js';
 export { createStyles, flattenStyle } from './styles.js';
-export { windowIdOf, useWindowId, useTopLevelWindow } from './windowid.js';
+export {
+  windowIdOf,
+  useWindowId,
+  windowHandleOf,
+  useWindowHandle,
+  useTopLevelWindow,
+} from './windowid.js';
 export { launchTimestamp, notifyStartupComplete } from './startup.js';
 export { activateWindow } from './activate.js';
 export { lastInputTime, serverTime } from './inputtime.js';
@@ -14,9 +20,30 @@ export {
   registerApplication,
 } from './application.js';
 export { useAppActivate, useAppOpen } from './apphooks.js';
-export { setBadge, setProgress, setQuicklist, setUrgent } from './launcher.js';
-export { useBadge, useDockMenu, useProgress } from './launcherhooks.js';
+export {
+  setBadge,
+  setLauncherMenu,
+  setProgress,
+  setQuicklist,
+  setUrgent,
+} from './launcher.js';
+export {
+  useBadge,
+  useDockMenu,
+  useLauncherMenu,
+  useProgress,
+} from './launcherhooks.js';
 export { useTray } from './trayhooks.js';
+// The Windows taskbar's own surfaces. Exported unconditionally and inert
+// where the backend has none — `useDesktopCapability('launcher').features`
+// carries `tasks`, `thumbnailToolbar` and `recentDocuments`, so an app
+// branches on what this desktop has rather than on the platform.
+export {
+  noteRecentDocument,
+  useJumpList,
+  useRecentDocument,
+  useThumbnailToolbar,
+} from './taskbarhooks.js';
 export {
   CAPABILITIES,
   NO_CAPABILITY,

package/src/launcher.js

@@ -6,7 +6,7 @@
 // desktops, two mechanisms, one call each:
 //
 //   1. **the app's own tile** — the cocoa backend's `NSDockTile`, reached
-//      through the app object (`setDockBadge`, `setDockMenu`, src/cocoa/
+//      through the app object (`setDockBadge`, `setLauncherMenu`, src/cocoa/
 //      app.js).
 //   2. **`com.canonical.Unity.LauncherEntry`** over the session bus — the
 //      protocol Unity defined and the KDE, elementary, Cairo-Dock and
@@ -34,13 +34,13 @@
 // is runtime, it follows state, and Dash-to-Dock/ubuntu-dock, Plank and the
 // Unity heritage launchers all render it.
 //
-// So `useDockMenu()` has a Linux rung after all, and the three menus an app
+// So `useLauncherMenu()` has a Linux rung after all, and the three menus an app
 // puts on the desktop — panel, tray, launcher — are now one authoring model
 // on both backends. `.desktop` actions are still the right place for entries
 // that must work *while the app is not running*; they are a different feature
 // wearing a similar hat.
 //
-// Nothing here imports react: `useBadge`/`useDockMenu` (launcherhooks.js) are
+// Nothing here imports react: `useBadge`/`useLauncherMenu` (launcherhooks.js) are
 // the hooks, and these are the functions under them, callable from host-side
 // code with no tree. The entry on the bus is held for as long as anything is
 // shown and released when the last of it is cleared — a held bus ref is a
@@ -300,7 +300,8 @@ export async function setUrgent(urgent, { app } = {}) {
 }
 
 /**
- * The menu behind a right-click on the app's launcher icon — the quicklist.
+ * The menu behind a right-click on the app's launcher icon — the Dock menu on
+ * macOS, the quicklist on Linux.
  *
  * Takes `MenuBar`'s item vocabulary and exports it as a `com.canonical.dbusmenu`
  * tree, exactly as the tray and the global menu do. `null` takes it down.
@@ -310,12 +311,12 @@ export async function setUrgent(urgent, { app } = {}) {
  * launcher that builds its client the instant it sees `quicklist` finds an
  * object there.
  */
-export async function setQuicklist(items, { app } = {}) {
+export async function setLauncherMenu(items, { app } = {}) {
   const target = app ?? soleApp();
 
-  // Rung 1: the app's own tile menu.
-  if (typeof target?.setDockMenu === 'function') {
-    target.setDockMenu(items ?? null);
+  // Rung 1: the app's own icon menu.
+  if (typeof target?.setLauncherMenu === 'function') {
+    target.setLauncherMenu(items ?? null);
     return true;
   }
 
@@ -367,6 +368,14 @@ export async function setQuicklist(items, { app } = {}) {
   return true;
 }
 
+/**
+ * @deprecated Renamed to {@link setLauncherMenu}. "Quicklist" is the Unity
+ * launcher's word for the menu macOS calls the Dock menu; this function
+ * always drove both, and the name only ever named one of them. Kept working
+ * and kept quiet.
+ */
+export const setQuicklist = setLauncherMenu;
+
 /** Test seam, not public: drop the exported entry without emitting. */
 export async function _resetLauncher() {
   await releaseEntry();

package/src/launcherhooks.js

@@ -1,4 +1,4 @@
-// `useBadge()`, `useProgress()` and `useDockMenu()` — the launcher's view of
+// `useBadge()`, `useProgress()` and `useLauncherMenu()` — the launcher's view of
 // the app, as things a component declares rather than manages.
 //
 // All three now have a rung on both backends except progress, which has one
@@ -7,7 +7,7 @@
 // feature an app should branch on, and a development warning for every
 // desktop that lacks one is a warning nobody can act on.
 //
-// The one that changed shape is `useDockMenu`. It used to be cocoa-only on
+// The one that changed shape is `useLauncherMenu`. It used to be cocoa-only on
 // the grounds that the freedesktop counterpart was an install step — see
 // `launcher.js`, where that reasoning is corrected: the launcher protocol
 // carries a `quicklist` dbusmenu, so the Dock menu is runtime code on both.
@@ -15,7 +15,7 @@
 import { useEffect, useRef } from 'react';
 
 import { useAppOrNull } from './appcontext.js';
-import { setBadge, setProgress, setQuicklist } from './launcher.js';
+import { setBadge, setLauncherMenu, setProgress } from './launcher.js';
 
 /**
  * Show `value` on the app's icon while this component is mounted, and clear
@@ -63,12 +63,12 @@ export function useProgress(value) {
 }
 
 /**
- * The menu behind a right-click on the app's icon in the Dock or launcher,
- * from the same `items` vocabulary `MenuBar` and `ContextMenu` take — an
- * item's `onSelect` fires when the user picks it.
+ * The menu behind a right-click on the app's **launcher icon** — the Dock on
+ * macOS, the launcher on Linux — from the same `items` vocabulary `MenuBar`
+ * and `ContextMenu` take. An item's `onSelect` fires when the user picks it.
  *
  * ```jsx
- * useDockMenu([
+ * useLauncherMenu([
  *   { label: 'New Window', onSelect: openWindow },
  *   { type: 'separator' },
  *   { label: 'Recent', items: recent.map(toItem) },
@@ -80,8 +80,14 @@ export function useProgress(value) {
  * backend; the launcher protocol's `quicklist` on Linux, which needs the
  * identity `registerApplication({ appId })` establishes and a `.desktop` file
  * of that name for a launcher to attach it to.
+ *
+ * It reads `useDesktopCapability('launcher').features.menu`, which is where
+ * the name comes from: every desktop has one icon standing for this
+ * application and calls it something different — Dock, taskbar, panel, dash —
+ * and `launcher` is the one word that is none of their words and all of their
+ * meanings (AGENTS.md, "Vocabulary").
  */
-export function useDockMenu(items) {
+export function useLauncherMenu(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
@@ -89,12 +95,20 @@ export function useDockMenu(items) {
   live.current = items;
 
   useEffect(() => {
-    setQuicklist(items ?? null, { app }).catch(() => {});
+    setLauncherMenu(items ?? null, { app }).catch(() => {});
   }, [items, app]);
 
   useEffect(() => {
     return () => {
-      setQuicklist(null, { app }).catch(() => {});
+      setLauncherMenu(null, { app }).catch(() => {});
     };
   }, [app]);
 }
+
+/**
+ * @deprecated Renamed to {@link useLauncherMenu}. "Dock" is one desktop's
+ * word for the icon every desktop has; this hook drove the Linux launcher's
+ * quicklist long before the name caught up. Kept working, and kept quiet —
+ * an alias that warned would punish an app for code that is still correct.
+ */
+export const useDockMenu = useLauncherMenu;

package/src/node.d.ts

@@ -40,7 +40,7 @@ export interface ImageDataLike {
 /**
  * The 2d context a node paints into — the canvas-shaped subset **both**
  * backends implement: ntk's `RenderingContext2D` over XRender on X11, and
- * `CocoaContext2D` over CoreGraphics on macOS. Declared as the contract an
+ * `BackendContext2D` over CoreGraphics on macOS. Declared as the contract an
  * element may rely on rather than as either class: what is here is on
  * both, and a member one backend has and the other does not is optional
  * here or absent. Coordinates are device pixels in the owning window's

package/src/nodes/cascade.js

@@ -422,6 +422,15 @@ export class NodeCascade {
   get placed() {
     const owner = this.isWindow ? this : this.root;
     if (!owner) return false;
+    // A window written under a root `<ThemeProvider>` is handed that palette
+    // when the scope inserts it, which is after it and its subtree were built
+    // and first resolved (nodes/scope.js `insertBefore`). Until then its
+    // ancestry is as incomplete as a popup's without its parent, and every
+    // token the provider defines would be reported as unknown — a warning for
+    // a style that then resolves correctly, and under
+    // `REACT_X11_STRICT_TOKENS=1` a throw that killed an app whose palette was
+    // fine.
+    if (owner._awaitsRootScope && owner._scope == null) return false;
     return owner.isPopup ? owner.parent != null : true;
   }
 

package/src/nodes/node.js

@@ -70,7 +70,12 @@ export class Node {
     return DEVTOOLS_FAKE_DOCUMENT;
   }
 
-  constructor(kind, props, app, { yoga = true } = {}) {
+  constructor(kind, props, app, { yoga = true, awaitsRootScope = false } = {}) {
+    // Set before anything resolves a style: a `<window>`'s own style is
+    // resolved by this constructor, and whether its ancestry is complete
+    // decides whether an unresolved `$token` is reported (cascade.js
+    // `placed`). A window under a root `<ThemeProvider>` has no palette yet.
+    this._awaitsRootScope = awaitsRootScope;
     this.kind = kind;
     this.props = props;
     this.app = app;

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/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>> {