react-x11 2.16.1 → 2.17.1

package/README.md

@@ -18,9 +18,10 @@ Build GUI programs for a Linux desktop, for a display at the other end of an
 ssh connection, or as a native Mac app, with your React / React Native
 experience — flexbox layout, components, hooks, synthetic events.
 
-### Two backends, one tree
+### Four backends, one tree
 
-The same components, the same hooks and the same `style` objects run on both:
+The same components, the same hooks and the same `style` objects run on all
+of them. The two that are mature:
 
 - **X11** ([the flagship](docs/remote.md)) — a Linux desktop, a display
   forwarded over `ssh -X`, `Xvfb` in CI, a thin client, or macOS through
@@ -35,20 +36,25 @@ The same components, the same hooks and the same `style` objects run on both:
   thin mechanism-only Objective-C++ bridge — an optional dependency shipping
   prebuilds, absent on Linux installs.
 
-`createRoot()` picks for you: **Cocoa on macOS** when the bridge is
-installed, X11 via `$DISPLAY` everywhere else, and X11 on a Mac without the
-bridge so an XQuartz setup keeps working. `createRoot({ backend: 'x11' })`
-or `REACT_X11_BACKEND=x11` pins it. On macOS the app's JS runs on a worker
+`createRoot()` picks for you: **Cocoa on macOS** and **win32 on Windows**
+when the matching bridge is installed, X11 via `$DISPLAY` everywhere else —
+and X11 on either of those without its bridge, so an XQuartz or WSLg setup
+keeps working. `createRoot({ backend: 'x11' })` or `REACT_X11_BACKEND=x11`
+pins it. On macOS the app's JS runs on a worker
 while AppKit keeps the main thread, so a menu, a drag or a live resize never
 stops it — `node app.js` is enough, and `REACT_X11_THREADED=0` keeps the
 main thread ([docs/macos.md](docs/macos.md#js-on-a-worker-a-ui-thread-of-the-bridges-own)).
 
-Two more backends are on the way, and the goal they serve is **full
-cross-platform support**: **Windows** — Win32 windows, Direct2D and
-DirectWrite, DWM compositing — with [docs/windows.md](docs/windows.md) as
-its PRD, and **native Wayland**, with [docs/wayland.md](docs/wayland.md)
-as its RFC. Both arrive as backends beside these two, not replacements for
-either: the same tree, the same components, the same `style` objects.
+Two more backends exist beside these, serving the goal of **full
+cross-platform support**, and both are younger than the two above.
+**native Wayland** ([docs/wayland.md](docs/wayland.md)) is opt-in rather than
+automatic, because X11 stays the default on Linux — the remote case is the
+flagship reason this project exists and Wayland has no network transparency.
+**Windows** ([docs/windows.md](docs/windows.md)) — Win32 windows, Direct2D
+and DirectWrite, DWM compositing through DirectComposition — renders and
+takes mouse input, with the desktop integrations still to come. Each is a
+backend beside the others rather than a replacement for any of them: the
+same tree, the same components, the same `style` objects.
 
 Layout is [yoga-layout](https://www.npmjs.com/package/yoga-layout) (WASM) on
 both, and text shaping is [fontkit](https://github.com/foliojs/fontkit) on
@@ -125,17 +131,26 @@ That is the shape of the problem this is good at:
 And the shape it is not good at, so you can stop here rather than in week
 three:
 
-- **Windows — today.** There is no Windows backend yet, so an app that has
-  to ship on Windows now wants Electron or Tauri. One is coming: a native
-  backend over Win32 windows, Direct2D and DirectWrite, composited by DWM
-  through DirectComposition, on a mechanism-only bridge shaped like the
-  Cocoa one. [docs/windows.md](docs/windows.md) is the PRD, from the
-  threading model up to what each desktop integration becomes. Two targets
-  ship meanwhile — X11 and Cocoa — and they are not the same app: the
-  desktop-shell half of X11 (`<foreign>` embedding, panel struts,
-  substructure redirect, the window-manager example below) has no macOS
-  equivalent, and `react-x11/test` drives the X11 backend only.
-  [docs/macos.md](docs/macos.md) says which is which.
+- **Windows — today.** The Windows backend is young, and further along than
+  that sounds. Win32 windows composited by DWM through DirectComposition,
+  Direct2D and DirectWrite behind the same contracts the Cocoa backend
+  proved, OpenGL, the keyboard and all five mouse buttons, popups, the
+  clipboard, file dialogs, the tray, the taskbar, global hotkeys,
+  notifications and window states — on a mechanism-only bridge shaped like
+  the Cocoa one, with a test suite and CI of its own. The examples run.
+  Drag and drop works both ways with the desktop, and the taskbar's own
+  surfaces — a thumbnail toolbar, a jump list, recent documents — are there
+  behind a capability, so an app that also runs elsewhere asks
+  `useSupports()` rather than the platform. What it does not have is **IME
+  and screen-reader support**: an app is unusable with a screen reader and
+  in CJK input. So an app that needs either on Windows _this month_ still
+  wants Electron or Tauri.
+  [docs/windows-integrations.md](docs/windows-integrations.md) is the
+  measured status and [docs/windows.md](docs/windows.md) the design. The three
+  targets are not the same app: the desktop-shell half of X11 (`<foreign>`
+  embedding, panel struts, substructure redirect, the window-manager example
+  below) has no macOS or Windows equivalent, and `react-x11/test` drives the
+  X11 backend only. [docs/macos.md](docs/macos.md) says which is which.
 - **native Wayland — today.** There is no Wayland backend yet. Ordinary
   application windows work fine on a Wayland desktop through Xwayland, which
   is not going away — but the desktop-shell half of X11 (panel struts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.16.1",
+  "version": "2.17.1",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -33,6 +33,7 @@
     "examples:attention": "tsx examples/attention.jsx",
     "examples:badge": "tsx examples/badge.jsx",
     "examples:tray": "tsx examples/tray.jsx",
+    "examples:taskbar": "tsx examples/taskbar.jsx",
     "examples:desktop": "tsx examples/desktop.jsx",
     "examples:tooltips": "tsx examples/tooltips.jsx",
     "examples:chat": "tsx examples/chat.jsx",
@@ -109,6 +110,7 @@
   "optionalDependencies": {
     "@windowkit/appkit": "^0.12.0",
     "@windowkit/wayland": "^3.1.1",
+    "@windowkit/win32": "^0.0.1",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.9.0"
   },

package/src/Reconciler.js

@@ -116,6 +116,9 @@ const ROOT_CONTEXT = Object.freeze({
   isInsideText: false,
   isInsideSvg: false,
   atRoot: true,
+  // Nothing is above the root, so a window written straight into it waits for
+  // no palette — unlike one under a `<ThemeProvider>` there.
+  underRootScope: false,
   inWindow: false,
 });
 
@@ -191,6 +194,11 @@ const HostConfig = {
       // Still at the root under a `<ThemeProvider>` written there, which
       // draws nothing; under anything else, inside a window.
       atRoot: parentHostContext.atRoot && type === THEME_SCOPE,
+      // *Below* one of those providers, which is a different fact: a window
+      // here is handed its palette when the scope inserts it, after it was
+      // built. `atRoot` is true at the root itself, where no provider is
+      // waiting to hand anything over, so the two cannot be one flag.
+      underRootScope: parentHostContext.atRoot && type === THEME_SCOPE,
       // Directly inside a window, where a provider can hand a nested window
       // on to it.
       inWindow: type === 'window' || type === 'popup',
@@ -255,10 +263,19 @@ const HostConfig = {
       case 'window':
         // No X11 calls here: the render phase may be discarded. The real
         // window is created top-down in the commit phase (realize).
+        // `underRootScope` goes in at construction, not after it: this
+        // constructor resolves the window's own style, and a window under a
+        // root `<ThemeProvider>` is handed that palette only when the scope
+        // inserts it (nodes/scope.js). Until then its ancestry is incomplete
+        // and every `$token` the provider defines would be reported as
+        // unknown — a warning for a style that resolves correctly a moment
+        // later, and under `REACT_X11_STRICT_TOKENS=1` a throw that killed an
+        // app whose palette was fine.
         node = new WindowNode(
           rootContainer,
           windowAttributes(props, scaleOf(rootContainer)),
           props,
+          { awaitsRootScope: hostContext.underRootScope },
         );
         break;
       case 'popup':
@@ -641,11 +658,18 @@ const isNtkApp = (v) =>
  */
 function resolveBackend(options) {
   const asked = options.backend ?? process.env.REACT_X11_BACKEND ?? 'auto';
-  if (asked === 'x11' || asked === 'cocoa' || asked === 'wayland') return asked;
+  if (
+    asked === 'x11' ||
+    asked === 'cocoa' ||
+    asked === 'wayland' ||
+    asked === 'win32'
+  ) {
+    return asked;
+  }
   if (asked !== 'auto') {
     throw new Error(
       `react-x11: unknown backend ${JSON.stringify(asked)} — expected ` +
-        "'x11', 'cocoa', 'wayland' or 'auto'.",
+        "'x11', 'cocoa', 'wayland', 'win32' or 'auto'.",
     );
   }
   // Naming an X endpoint is choosing X11: a `display` or a `stream` (the
@@ -655,7 +679,13 @@ function resolveBackend(options) {
   if (options.display !== undefined || options.stream !== undefined) {
     return 'x11';
   }
-  return process.platform === 'darwin' ? 'cocoa' : 'x11';
+  if (process.platform === 'darwin') return 'cocoa';
+  // Windows has no X server to fall back to in the ordinary case, so 'auto'
+  // reaches for the native backend the way it does on a mac — and falls back
+  // to X11 below if the bridge is not installed, which is what keeps a Cygwin
+  // or WSLg setup with DISPLAY set working.
+  if (process.platform === 'win32') return 'win32';
+  return 'x11';
 }
 
 // What a root that opens its own connection forwards to ntk. `stream` is
@@ -769,17 +799,27 @@ export async function createRoot(options = {}) {
   // synchronous block, and only where the handshake takes longer than it. It
   // is not measurable on a Unix socket, and it is lost in the noise on a link
   // slow enough to matter. This is the right order, not a fast one.
-  const connectX11 = () =>
-    connect(
-      Object.fromEntries(
-        CONNECT_OPTIONS.filter((k) => rest[k] !== undefined).map((k) => [
-          k,
-          rest[k],
-        ]),
-      ),
+  // `REACT_X11_FONT_SOURCE` is the companion to `REACT_X11_BACKEND` above:
+  // an A/B run without touching code. ntk finds its fonts through fontconfig,
+  // and a machine with no `fc-match` — a slim container, or Windows, where
+  // the X11 backend is only ever run to compare it against the native one —
+  // has to be told where the fonts are instead. An explicit `fontSource`
+  // wins; this only fills the gap.
+  const connectX11 = () => {
+    const options = Object.fromEntries(
+      CONNECT_OPTIONS.filter((k) => rest[k] !== undefined).map((k) => [
+        k,
+        rest[k],
+      ]),
     );
+    options.fontSource ??= process.env.REACT_X11_FONT_SOURCE || undefined;
+    if (options.fontSource === undefined) delete options.fontSource;
+    return connect(options);
+  };
   const cocoaAsked =
     rest.backend === 'cocoa' || process.env.REACT_X11_BACKEND === 'cocoa';
+  const win32Asked =
+    rest.backend === 'win32' || process.env.REACT_X11_BACKEND === 'win32';
   const connecting = !owned
     ? Promise.resolve(borrowed)
     : backend === 'wayland'
@@ -791,25 +831,44 @@ export async function createRoot(options = {}) {
         import('./wayland/app.js').then(({ createWaylandApp }) =>
           createWaylandApp(rest),
         )
-      : backend === 'cocoa'
-        ? import('./cocoa/app.js')
-            .then(({ createCocoaApp }) => createCocoaApp(rest))
+      : backend === 'win32'
+        ? import('./win32/app.js')
+            .then(({ createWin32App }) => createWin32App(rest))
             .catch((err) => {
-              // Asked for by name, the bridge is required and its absence is
-              // the error (it says how to install). Reached by 'auto', a mac
-              // without it falls back to X11 so an XQuartz setup keeps
-              // working — said once, because a silent fallback would look
-              // like the native backend being broken rather than absent.
-              if (cocoaAsked) throw err;
+              // Same bargain as cocoa's below: asked for by name the bridge is
+              // required and its absence is the error, reached by 'auto' a
+              // machine without it falls back to X11 so a WSLg or Cygwin setup
+              // with DISPLAY set keeps working — said once, because a silent
+              // fallback reads as the native backend being broken rather than
+              // absent.
+              if (win32Asked) throw err;
               if (process.env.NODE_ENV !== 'production') {
                 console.warn(
-                  'react-x11: no @windowkit/appkit bridge — falling back to the ' +
+                  'react-x11: no @windowkit/win32 bridge — falling back to the ' +
                     `X11 backend. (${err.message.split('\n')[0]})`,
                 );
               }
               return connectX11();
             })
-        : connectX11();
+        : backend === 'cocoa'
+          ? import('./cocoa/app.js')
+              .then(({ createCocoaApp }) => createCocoaApp(rest))
+              .catch((err) => {
+                // Asked for by name, the bridge is required and its absence is
+                // the error (it says how to install). Reached by 'auto', a mac
+                // without it falls back to X11 so an XQuartz setup keeps
+                // working — said once, because a silent fallback would look
+                // like the native backend being broken rather than absent.
+                if (cocoaAsked) throw err;
+                if (process.env.NODE_ENV !== 'production') {
+                  console.warn(
+                    'react-x11: no @windowkit/appkit bridge — falling back to the ' +
+                      `X11 backend. (${err.message.split('\n')[0]})`,
+                  );
+                }
+                return connectX11();
+              })
+          : connectX11();
   const layout = loadLayout();
   const integrations = loadIntegrations(); // null when there is nothing to install
   const [app] = await Promise.all([connecting, layout, integrations]);
@@ -843,7 +902,7 @@ export async function createRoot(options = {}) {
   // critical path — every rung that fails is a normal, silent "off"
   // (docs/accessibility.md). Deliberately not awaited: a root must not
   // wait on a bus that is not there.
-  startA11y();
+  startA11y(app);
 
   // Before anything renders: the launch id has to be on the first toplevel
   // before it maps, and the environment variable has to be consumed whether

package/src/a11y.js

@@ -1275,12 +1275,29 @@ function a11yEnabled() {
  * it stopped — which is the debugging story for "why does Orca not see my
  * app".
  */
-export function startA11y() {
+export function startA11y(app) {
   if (startPromise) return startPromise;
   if (!a11yEnabled()) {
     startPromise = Promise.resolve(null);
     return startPromise;
   }
+  // A backend with an accessibility bridge of its own answers first, and its
+  // presence *is* the capability — the same rule the rest of the library
+  // uses. The Windows backend installs one, because UI Automation asks
+  // synchronously and has to be answered from a pushed copy rather than from
+  // the live tree (docs/windows.md §Accessibility); AT-SPI's asynchronous
+  // questions are answered from the tree itself, below.
+  if (typeof app?.startAccessibility === 'function') {
+    startPromise = Promise.resolve()
+      .then(() => app.startAccessibility())
+      .catch((err) => {
+        if (process.env.REACT_X11_A11Y) {
+          console.warn('react-x11: accessibility bridge failed to start:', err);
+        }
+        return null;
+      });
+    return startPromise;
+  }
   startPromise = import('./atspi.js')
     .then((atspi) => atspi.start())
     .catch((err) => {

package/src/appcontext.js

@@ -80,6 +80,14 @@ const FEATURES = {
   },
   embedding: { watch: NEVER_CHANGES, read: canEmbed },
   glOverlay: { watch: NEVER_CHANGES, read: canOverlay },
+  // Everything here is a property of the **display**: what the server, the
+  // compositor and the drawing pipeline can do. A desktop's own surfaces --
+  // a tray, a launcher icon and what hangs off it, a notification daemon --
+  // are a different question with a different shape, because they can appear
+  // and vanish while the process runs and because "available" alone is a lie
+  // about them. They go through `desktopCapability()` (src/capabilities.js),
+  // which answers `{ available, backend, features }`. Adding one here would
+  // flatten that to a boolean and lose the mechanism with it.
 };
 
 /**

package/src/appearance.js

@@ -955,6 +955,38 @@ async function macosRung() {
   return runWatcher();
 }
 
+// --------------------------------------------------------------------------
+// Rung 4: Windows
+// --------------------------------------------------------------------------
+
+/**
+ * The backend answers this one rather than this file reaching for a bridge:
+ * the values live behind a native addon that exists only on Windows, and
+ * asking the app for them is the capability test every other ladder here
+ * makes (AGENTS.md, "Find the mechanism, not the platform").
+ *
+ * All four values come from one source — the Personalize key for light or
+ * dark, DWM for the accent, and the two accessibility flags from
+ * `SystemParametersInfo` — so this rung owns every field, which is the rule
+ * the ladder is ordered for.
+ *
+ * Live rather than polled: Windows broadcasts `WM_SETTINGCHANGE`,
+ * `WM_THEMECHANGED` and `WM_DWMCOLORIZATIONCOLORCHANGED` to every top-level
+ * window, and the bridge's UI thread has one.
+ */
+async function windowsRung(app) {
+  if (typeof app?.systemAppearance !== 'function') return false;
+  const values = app.systemAppearance();
+  if (!values) return false;
+  publish(values, 'windows');
+  app.onAppearanceChange?.(() => {
+    if (owner !== 'windows') return;
+    const next = app.systemAppearance();
+    if (next) publish(next, 'windows');
+  });
+  return true;
+}
+
 // Killed rather than left behind: `unref()` keeps it from holding *this*
 // process open, and nothing keeps it from outliving it.
 process.on('exit', () => {
@@ -975,6 +1007,10 @@ async function runLadder(app) {
     // an XQuartz display never reaches this at all, which is correct — it
     // cannot read that Mac's defaults.
     ['macos', macosRung],
+    // Before XSETTINGS for the same reason macOS is: where the process is
+    // Windows, the desktop's own preference is the one the user set, and an
+    // XSETTINGS daemon there would be something they installed by hand.
+    ['windows', () => windowsRung(app)],
     ['xsettings', () => xsettingsRung(app)],
   ]) {
     let answered = false;

package/src/{cocoa → backend}/context2d.js

@@ -1,9 +1,23 @@
-// A canvas-shaped 2d context over a @windowkit/appkit CoreGraphics surface.
+// A canvas-shaped 2d context over a **verb table** — the drawing dialect
+// every native backend answers, and the one place it is written down.
 //
-// This is the raster half of the Cocoa backend: on the surface presenter it
-// is the whole drawing path, and on the layer presenter it stays as the
-// fallback every painted-code node (<canvas>, <svg>, registered elements)
-// rasters through — docs/macos.md §"Custom drawing on a layer tree".
+// This is macos.md §"The split" step 4, taken when a second native backend
+// started: the class takes its `native` as a constructor argument and calls
+// nothing else, so one wrapper drives @windowkit/appkit's CoreGraphics verbs
+// and @windowkit/win32's Direct2D verbs alike. A bridge that lacks an
+// optional verb is feature-detected (`ctxSetBlendMode`, `blitSurface`,
+// `ctxDrawSymbol`) and degrades rather than throwing.
+//
+// **Wayland is deliberately not here.** src/wayland/context2d.js is not
+// another copy of this file — it is a GLES rasterizer, wayland.md's Tier D,
+// which implements the same dialect by drawing it rather than by forwarding
+// it. The two are different layers, not duplicates, and folding one into the
+// other would lose that.
+//
+// On the surface presenter this is the whole drawing path; on the layer
+// presenter it stays as the fallback every painted-code node (<canvas>,
+// <svg>, registered elements) rasters through — docs/macos.md §"Custom
+// drawing on a layer tree".
 //
 // The native surface holds the real graphics state (paths, CTM, clip); this
 // class keeps the JS-visible state (fillStyle strings, gradient objects,
@@ -265,7 +279,7 @@ class SolidPicture {
   }
 }
 
-export class CocoaContext2D {
+export class BackendContext2D {
   /**
    * @param native the @windowkit/appkit module
    * @param surfaceOf () => current surface handle — the owner replaces the
@@ -1425,9 +1439,15 @@ export class CocoaContext2D {
     const family = m ? m[4] : 'sans-serif';
     const weight = m?.[2] === 'bold' ? 700 : m?.[2] ? Number(m[2]) : 400;
     const style = m?.[1] ? 'italic' : 'normal';
+    // No colour unless the caller named one, which is what `_contextInk`
+    // above is waiting for: a layout with no ink of its own is drawn with the
+    // context's fill, the way `fillText` is defined to be. Defaulting the
+    // base to black instead made every layout carry an ink, so `fillStyle`
+    // was read, found to be irrelevant, and never applied — a `fillText`
+    // under a white fill came out black on both backends.
     return fonts.layout(
       [{ text: String(text), family, size, weight, style, color }],
-      { family, size, weight, style, color: color ?? '#000' },
+      { family, size, weight, style, color },
       {},
     );
   }

package/src/capabilities.js

@@ -79,6 +79,21 @@ function soleApp() {
   return showing.length === 1 ? showing[0] : null;
 }
 
+/**
+ * The mechanism a backend says it built one rung on, or null.
+ *
+ * Backends install the *same method names* for the same rung on purpose --
+ * `createStatusItem` is how `useTray` stays one hook -- so a method name
+ * cannot tell two mechanisms apart, and a probe that tried reported
+ * Shell_NotifyIcon as `cocoa`. A backend with more than one mechanism to
+ * distinguish declares them (`app.shellMechanisms`); one with nothing to
+ * disambiguate says nothing and the method checks below still answer.
+ */
+function shellMechanism(target, rung) {
+  const declared = target?.shellMechanisms;
+  return typeof declared?.[rung] === 'string' ? declared[rung] : null;
+}
+
 // ---------------------------------------------------------------------------
 // notifications
 // ---------------------------------------------------------------------------
@@ -154,6 +169,27 @@ async function probeNotifications({ app } = {}) {
     });
   }
 
+  if (backend === 'win32') {
+    // A Shell_NotifyIcon balloon: text with a severity, shown by the tray
+    // icon and kept by the Action Center afterwards. Everything richer is a
+    // toast, which is WinRT and a different mechanism entirely.
+    return frozen('win32', {
+      actions: false,
+      events: false, // NIN_BALLOONUSERCLICK is not routed
+      update: false,
+      close: false,
+      body: true,
+      bodyMarkup: false,
+      bodyImage: false,
+      // The balloon shows the severity's own glyph. NIIF_USER would put the
+      // caller's icon there and is not wired up, so an icon cannot be chosen.
+      icon: false,
+      sound: true, // the shell plays one; NIIF_NOSOUND is not set
+      persistence: true, // it lands in the Action Center
+      urgency: true, // low/normal/critical -> NIIF_NONE/INFO/ERROR
+    });
+  }
+
   // `osascript` and `notify-send`: one way, and that is the whole of it.
   // `notify-send -p` prints an id on newer libnotify, which is why `update`
   // is not flatly false there — see notifications.js.
@@ -178,6 +214,33 @@ async function probeNotifications({ app } = {}) {
 
 /** The tray on an app that has one of its own, which needs nothing asked. */
 function trayNow(target) {
+  // The mechanism is *declared* by the backend, not guessed from a method
+  // name, because two backends deliberately install the same names -- that
+  // sharing is what lets `useTray` be one hook -- and a probe that read
+  // `createStatusItem` as "this is AppKit" reported Shell_NotifyIcon as
+  // `cocoa`, with SF Symbols and click modifiers it does not have.
+  if (shellMechanism(target, 'tray') === 'shellnotifyicon') {
+    return frozen('shellnotifyicon', {
+      menu: true,
+      // No name vocabulary: the shell has no icon theme to look a name up
+      // in, so an icon here is always pixels or a file.
+      iconName: false,
+      iconBytes: true,
+      attention: false,
+      overlay: false,
+      tooltip: true,
+      // An NSStatusItem can show a label beside its icon; a notify icon is
+      // an icon. `title` is accepted and used as the tooltip, which is a
+      // fallback rather than the feature.
+      title: false,
+      click: true,
+      clickPosition: true,
+      clickRect: false,
+      clickModifiers: false,
+      // WM_MOUSEWHEEL is not delivered to a notify icon.
+      scroll: false,
+    });
+  }
   if (typeof target?.createStatusItem === 'function') {
     return frozen('cocoa', {
       menu: true,
@@ -234,15 +297,45 @@ async function probeTray({ app } = {}) {
 
 /** The Dock tile on an app that has one, which needs nothing asked. */
 function launcherNow(target) {
+  // Declared, not guessed -- see `trayNow`. This backend installs
+  // `setDockBadge` too, so the cocoa branch below used to answer for it and
+  // say `progress: false` with a working taskbar progress bar right there.
+  if (shellMechanism(target, 'launcher') === 'taskbar') {
+    return frozen('taskbar', {
+      badge: true,
+      // Drawn into the overlay icon, so it is text rather than a count --
+      // but a 16x16 overlay holds about three glyphs and longer labels come
+      // out as `99+`.
+      badgeText: true,
+      progress: true, // ITaskbarList3::SetProgressValue
+      urgent: true, // FlashWindowEx
+      // The taskbar button's menu is the jump list, whose entries start a
+      // *new* process; nothing on it can call back into this one. That is a
+      // different feature from the Dock menu, and `tasks` is its name --
+      // reporting `menu: true` here would promise a callback that never
+      // comes.
+      menu: false,
+      needsDesktopFile: false,
+      tasks: typeof target.jumpList === 'function',
+      thumbnailToolbar: typeof target.thumbnailToolbar === 'function',
+      recentDocuments: typeof target.noteRecentDocument === 'function',
+    });
+  }
   if (typeof target?.setDockBadge === 'function') {
     return frozen('cocoa', {
       badge: true,
       badgeText: true, // the tile takes any label
       progress: false, // NSDockTile has no progress bar
       urgent: true, // requestUserAttention, via window states
-      menu: typeof target.setDockMenu === 'function',
+      menu: typeof target.setLauncherMenu === 'function',
       // The Dock always shows the app; nothing has to be installed for it.
       needsDesktopFile: false,
+      // The Dock has no static-task menu and no hover toolbar. macOS does
+      // keep a Recent list (`noteNewRecentDocumentURL:`), but this backend
+      // has nothing wired to it, and the map says what the backend can do.
+      tasks: false,
+      thumbnailToolbar: false,
+      recentDocuments: typeof target.noteRecentDocument === 'function',
     });
   }
   return null;
@@ -283,6 +376,11 @@ async function probeLauncher({ app } = {}) {
     urgent: true,
     menu: true, // the quicklist
     needsDesktopFile: true,
+    // The quicklist is the menu; `Actions=` in the .desktop file are the
+    // closest thing to static tasks and are not driven from here.
+    tasks: false,
+    thumbnailToolbar: false,
+    recentDocuments: false,
   });
 }