react-x11 2.15.1 → 2.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.15.1",
+  "version": "2.15.3",
   "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:desktop": "tsx examples/desktop.jsx",
     "examples:tooltips": "tsx examples/tooltips.jsx",
     "examples:chat": "tsx examples/chat.jsx",
     "examples:clipboard": "tsx examples/clipboard.jsx",

package/src/application.js

@@ -346,6 +346,18 @@ function environmentContext() {
  * that was mounted after the launch it is asking about.
  */
 let current = null;
+/**
+ * The role of this process's registration, which is **not** the same question
+ * as `current`.
+ *
+ * `current` is the *primary* registration and is deliberately null for a
+ * second copy of an app, because a secondary must not own the badge or the
+ * launcher entry — the primary does. But "no registration at all" and "a
+ * registration that lost the race" are different facts, and a feature probe
+ * that cannot tell them apart tells an app author to call a function they
+ * already called. See `capabilities.js`.
+ */
+let currentRole = null;
 
 /**
  * The schemes the registration declared, kept beside it for the transports
@@ -675,6 +687,7 @@ export async function registerApplication(options = {}) {
     await registration.remove().catch(() => {});
     await forward(ref, dbus, { appId, objectPath, uris });
     await ref.release();
+    currentRole = 'secondary';
     const secondary = {
       role: 'secondary',
       appId,
@@ -711,7 +724,10 @@ export async function registerApplication(options = {}) {
     async release() {
       if (released) return;
       released = true;
-      if (current === primaryRegistration) current = null;
+      if (current === primaryRegistration) {
+        current = null;
+        currentRole = null;
+      }
       await ref.bus.releaseName(appId).catch(() => {});
       await registration?.remove().catch(() => {});
       registration = null;
@@ -721,6 +737,7 @@ export async function registerApplication(options = {}) {
   primaryRegistration[Symbol.asyncDispose] = () =>
     primaryRegistration.release();
   current = primaryRegistration;
+  currentRole = 'primary';
   return primaryRegistration;
 }
 
@@ -774,6 +791,12 @@ async function forward(ref, dbus, { appId, objectPath, uris }) {
   }
 }
 
+/** `'primary' | 'secondary' | null`. Not public — `capabilities.js` uses it to
+ *  tell "never registered" from "registered, but another copy is the app". */
+export function currentRegistrationRole() {
+  return currentRole;
+}
+
 /** This process's registration, or `null`. Not public; the docs use `role`. */
 export function currentRegistration() {
   return current;
@@ -782,6 +805,7 @@ export function currentRegistration() {
 /** Test seam, not public: forget every handler, buffer and registration. */
 export function _resetApplicationState() {
   current = null;
+  currentRole = null;
   currentSchemes = null;
   openHandlers.clear();
   activateHandlers.clear();

package/src/capabilities.js

@@ -0,0 +1,324 @@
+// What this desktop can actually do — feature discovery for the things an app
+// does *outside* its own windows.
+//
+// ## Why this is not `useSupports()`
+//
+// `useSupports()` answers questions about the **display**: is there a
+// compositor, is there a 32-bit visual, did this connection get the direct GL
+// backend. All of them are local, synchronous, and knowable before the first
+// frame.
+//
+// Everything on this page is the opposite on all three counts. Whether there
+// is a notification daemon, a tray host or a launcher listening is a fact
+// about **another process on a bus**, it takes a round trip to learn, and it
+// changes while the app runs — a panel restarts, an extension is toggled, a
+// user logs into a different session type. So the shape has to be render
+// state that settles and then follows, not a boolean that is right on the
+// first frame.
+//
+// ## Why a boolean is not enough
+//
+// "Does this desktop have notifications" is the wrong question, because the
+// answer is yes on machines that mean four different things by it:
+//
+//   - a freedesktop daemon with `actions` — a banner with buttons that call
+//     back into the app, updated in place, reporting what the user did;
+//   - a freedesktop daemon **without** `actions` — GNOME's own for years,
+//     and several minimal ones — where the same call shows a banner and the
+//     buttons silently never appear;
+//   - macOS's notification centre — actions and callbacks, but only for a
+//     signed bundle, and a different vocabulary underneath;
+//   - `notify-send` or `osascript` — one-way text with an urgency and an
+//     icon, no update, no close, no events, ever.
+//
+// An app that wants "reply from the notification" has to know which of those
+// it has, and the honest unit is therefore a **feature set**, not a flag. The
+// freedesktop daemons already publish exactly this through `GetCapabilities`;
+// this module's job is to translate every backend's answer into one portable
+// vocabulary so an app branches on the feature and never on the platform.
+//
+// ## The rule for adding one
+//
+// A capability name is a *thing an app wants to do*, and its features are the
+// parts of it that a backend can honestly lack. If a feature is missing
+// everywhere but one backend it is still a feature — `badgeText` is macOS's
+// alone and is listed — but if a "feature" is really a different way of doing
+// the same thing, it belongs in `backend` instead. Backends are named after
+// the mechanism (`statusnotifier`, `cocoa`, `notify-send`), never after the
+// platform, so that a second Linux mechanism does not need a second name for
+// Linux.
+
+import { sessionBus } from './bus.js';
+import { currentRegistration, currentRegistrationRole } from './application.js';
+import {
+  notificationBackend,
+  NOTIFICATIONS_NAME,
+  NOTIFICATIONS_PATH,
+} from './notifications.js';
+import { WATCHER_NAME } from './statusnotifier.js';
+import { liveApps } from './trace-registry.js';
+
+/** Every capability this module can answer for. */
+export const CAPABILITIES = ['notifications', 'tray', 'launcher'];
+
+/** The shape a probe resolves to when there is no mechanism at all. */
+const NONE = Object.freeze({ available: false, backend: null, features: {} });
+
+const frozen = (backend, features) =>
+  Object.freeze({
+    available: true,
+    backend,
+    features: Object.freeze(features),
+  });
+
+/** The app to ask when the caller did not say. Mirrors `launcher.js`. */
+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;
+}
+
+// ---------------------------------------------------------------------------
+// notifications
+// ---------------------------------------------------------------------------
+
+/**
+ * The freedesktop daemon's own `GetCapabilities`, translated.
+ *
+ * The daemon publishes a flat list of strings; the names below are the ones
+ * that change what an app may do. Anything not in the list is absent, which
+ * is why every field is read with `includes` rather than defaulted true —
+ * a daemon that lists nothing supports nothing but a banner.
+ */
+function fromDaemonCaps(caps) {
+  const has = (name) => caps.includes(name);
+  return {
+    // The two that decide whether a notification is a conversation or a sign.
+    actions: has('actions'),
+    events: has('actions'),
+    // Every fd.o daemon can replace and close by id; neither is advertised
+    // as a capability because the protocol requires both.
+    update: true,
+    close: true,
+    body: has('body'),
+    bodyMarkup: has('body-markup'),
+    bodyImage: has('body-images'),
+    icon: has('icon-static') || has('icon-multi'),
+    sound: has('sound'),
+    // The banner survives in a tray/centre rather than expiring unseen.
+    persistence: has('persistence'),
+    urgency: true,
+  };
+}
+
+async function probeNotifications({ app } = {}) {
+  const backend = await notificationBackend({ app });
+  if (!backend) return NONE;
+
+  if (backend === 'dbus') {
+    const ref = await sessionBus();
+    if (!ref) return NONE;
+    try {
+      const iface = await ref.bus.getInterface(
+        NOTIFICATIONS_NAME,
+        NOTIFICATIONS_PATH,
+        NOTIFICATIONS_NAME,
+      );
+      const caps = await new Promise((resolve) => {
+        iface.GetCapabilities((err, list) => resolve(err ? [] : (list ?? [])));
+      });
+      return frozen('dbus', fromDaemonCaps(caps));
+    } catch {
+      // The name is there but the object will not answer. A banner will
+      // probably still post; nothing richer should be promised.
+      return frozen('dbus', fromDaemonCaps([]));
+    } finally {
+      await ref.release();
+    }
+  }
+
+  if (backend === 'cocoa') {
+    return frozen('cocoa', {
+      actions: true,
+      events: true,
+      update: true,
+      close: true,
+      body: true,
+      bodyMarkup: false, // the centre renders plain text
+      bodyImage: true,
+      icon: true,
+      sound: true,
+      persistence: true,
+      urgency: true, // mapped onto interruption levels
+    });
+  }
+
+  // `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.
+  return frozen(backend, {
+    actions: false,
+    events: false,
+    update: backend === 'notify-send',
+    close: false,
+    body: true,
+    bodyMarkup: false,
+    bodyImage: false,
+    icon: true,
+    sound: false,
+    persistence: false,
+    urgency: backend === 'notify-send',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// tray
+// ---------------------------------------------------------------------------
+
+async function probeTray({ app } = {}) {
+  const target = app ?? soleApp();
+  if (typeof target?.createStatusItem === 'function') {
+    return frozen('cocoa', {
+      menu: true,
+      iconName: true, // SF Symbols
+      iconBytes: true,
+      attention: false, // no NeedsAttention equivalent on a status item
+      overlay: false,
+      tooltip: true,
+      title: true,
+      click: true,
+      clickPosition: true,
+      clickRect: true,
+      clickModifiers: true,
+      scroll: false,
+    });
+  }
+
+  const ref = await sessionBus();
+  if (!ref) return NONE;
+  try {
+    // A **live owner**, not an activatable name — see `statusnotifier.js`.
+    if (!(await ref.bus.nameHasOwner(WATCHER_NAME))) return NONE;
+  } catch {
+    return NONE;
+  } finally {
+    await ref.release();
+  }
+  return frozen('statusnotifier', {
+    menu: true,
+    iconName: true, // themed icon names, which is the good path here
+    iconBytes: true, // ARGB pixmaps
+    attention: true,
+    overlay: true,
+    tooltip: true,
+    title: true,
+    click: true,
+    clickPosition: true,
+    // The protocol carries none of these — see `statusnotifier.js`.
+    clickRect: false,
+    clickModifiers: false,
+    scroll: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// launcher
+// ---------------------------------------------------------------------------
+
+async function probeLauncher({ app } = {}) {
+  const target = app ?? soleApp();
+  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',
+      // The Dock always shows the app; nothing has to be installed for it.
+      needsDesktopFile: false,
+    });
+  }
+
+  // The Linux rung needs two things that are not the bus: an app id to
+  // attribute the entry to, and a `.desktop` file of that name for the
+  // launcher to hang it on. The first is knowable here; the second is not
+  // (it is a file on a path the launcher chooses), which is why it is
+  // reported as a *requirement* rather than as availability.
+  const ref = await sessionBus();
+  if (!ref) return NONE;
+  await ref.release();
+  if (!currentRegistration()?.appId) {
+    return Object.freeze({
+      available: false,
+      backend: null,
+      features: {},
+      // Two different "no"s, and only one is a mistake. A **secondary**
+      // instance called `registerApplication()` and lost the race for the
+      // name — the first copy owns the badge and the quicklist, which is the
+      // whole point of single-instance — so telling its author to call a
+      // function they already called sends them after a bug that is not
+      // there. The launcher is genuinely unavailable *to this process*
+      // either way; only the advice differs.
+      reason:
+        currentRegistrationRole() === 'secondary' ? 'not-primary' : 'no-app-id',
+    });
+  }
+  return frozen('launcherentry', {
+    badge: true,
+    badgeText: false, // the protocol carries a count and nothing else
+    progress: true,
+    urgent: true,
+    menu: true, // the quicklist
+    needsDesktopFile: true,
+  });
+}
+
+// ---------------------------------------------------------------------------
+
+const PROBES = {
+  notifications: probeNotifications,
+  tray: probeTray,
+  launcher: probeLauncher,
+};
+
+/**
+ * What this desktop can do for one feature, as a promise.
+ *
+ * ```js
+ * const n = await desktopCapability('notifications');
+ * if (n.features.actions) postWithReplyButton();
+ * else postPlainBanner();
+ * ```
+ *
+ * Resolves to `{ available, backend, features }`. `available` false means
+ * there is no mechanism at all and `features` is empty; otherwise `backend`
+ * names the mechanism — `'dbus'`, `'cocoa'`, `'statusnotifier'`,
+ * `'launcherentry'`, `'notify-send'`, `'osascript'` — and `features` is the
+ * portable vocabulary for this capability.
+ *
+ * **Never cached.** A panel restarting, an extension being enabled or a
+ * daemon being installed all change the answer, and a cached "no" would
+ * outlive every one of them. {@link useDesktopCapability} re-probes on the same
+ * events that would change it.
+ */
+export async function desktopCapability(name, options = {}) {
+  const probe = PROBES[name];
+  if (!probe) {
+    throw new TypeError(
+      `react-x11: desktopCapability(${JSON.stringify(name)}) — no such ` +
+        `capability. Expected ${CAPABILITIES.join(', ')}.`,
+    );
+  }
+  try {
+    return await probe(options);
+  } catch {
+    // A probe that throws is a desktop that could not be asked, which is the
+    // same outcome for a caller as one that answered no.
+    return NONE;
+  }
+}
+
+/** The "nothing here" answer, exported so a caller can compare against it and
+ *  so the hook has something stable to return on the first frame. */
+export const NO_CAPABILITY = NONE;

package/src/cocoa/app.js

@@ -38,6 +38,7 @@ import { CocoaPaneWindow } from './panewindow.js';
 import { CocoaColorSampler } from './screencolor.js';
 import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
+import { releaseImageUpload } from './context2d.js';
 import { CocoaSurface } from './surface.js';
 import { CocoaWindow } from './window.js';
 import { decodeKey, modifierMask } from './keymap.js';
@@ -449,6 +450,18 @@ export class CocoaApp {
     return new CocoaSurface(this, options);
   }
 
+  /**
+   * The release seam for an `Image`'s upload (`freeImage`, src/imagesource.js).
+   * `ctx.drawImage(image)` here composites from a CG bitmap made for the
+   * Image on its first draw, which ntk's `Image.destroy()` — written for X,
+   * where the upload is a pixmap it tracks itself — cannot see; an owner
+   * letting go of an Image calls this too, and the bitmap is freed on the
+   * call. An Image nobody releases takes its bitmap with it when collected.
+   */
+  releaseImage(image) {
+    releaseImageUpload(image);
+  }
+
   /**
    * The `useGlobalMenu` transport seam: same owner shape as the D-Bus
    * GlobalMenuExport (start/stop/update), pointed at the macOS menu bar.

package/src/cocoa/context2d.js

@@ -33,6 +33,100 @@ function parseColor(value) {
   return parsed;
 }
 
+/** Bytes as a Buffer over the same memory — for a view, its own window of
+ * the ArrayBuffer, not the whole buffer from offset 0. */
+function toBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (ArrayBuffer.isView(data)) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return Buffer.from(data);
+}
+
+// --- ntk Images as drawImage sources -----------------------------------------
+//
+// An ntk `Image` is straight RGBA in JS memory. On X, ntk uploads it to a
+// pixmap per connection and caches that on the Image; here the upload is a
+// CG bitmap made on the first draw and kept in this map, then composited
+// through `ctxDrawSurface` like any surface, scaling and cropping included.
+// The bridge's `ctxPutImageData` does the conversion — it premultiplies the
+// straight bytes into the bitmap's BGRA (ByteOrder32Host + AlphaFirst) —
+// so the bytes go over as the Image holds them.
+//
+// Images are immutable content (ntk's contract, and `<image>`'s), so an
+// entry is never refreshed. The map is keyed weakly: an Image that is
+// dropped takes its entry along and the handle's finalizer frees the
+// bitmap; an owner that is done with one frees it on the call instead,
+// through `releaseImageUpload` (the app's `releaseImage` seam).
+
+/** Image -> { native, handle } */
+const imageUploads = new WeakMap();
+
+/** An ntk `Image`: the duck type `isDirectImageSource` and ntk's own
+ * `drawImage` accept, plus the pixels this backend reads in place of the
+ * picture. A bare `{ width, height, data }` is not one — `ImageData` is
+ * written between draws, and caching it by identity would show stale
+ * pixels. */
+function isImagePixels(image) {
+  const { width, height, data } = image;
+  return (
+    typeof image.picture === 'function' &&
+    Number.isInteger(width) &&
+    Number.isInteger(height) &&
+    width > 0 &&
+    height > 0 &&
+    data?.length === width * height * 4
+  );
+}
+
+function uploadImage(native, image) {
+  const held = imageUploads.get(image);
+  if (held?.native === native) return held.handle;
+  const { width, height } = image;
+  const handle = native.createSurface(width, height, 1);
+  native.ctxPutImageData(handle, toBuffer(image.data), width, height, 0, 0);
+  imageUploads.set(image, { native, handle });
+  return handle;
+}
+
+/** Free an Image's bitmap now, if it has one; drawing it again uploads it
+ * again, as ntk's `destroy()` promises for its own copies. */
+export function releaseImageUpload(image) {
+  const held = image != null && imageUploads.get(image);
+  if (!held) return;
+  imageUploads.delete(image);
+  if (typeof held.native.releaseSurface === 'function') {
+    held.native.releaseSurface(held.handle);
+  }
+}
+
+const warnedSources = new Set();
+
+/** A source this backend has no pixels for, said once per kind in
+ * development — the alternative is an empty box and no reason. */
+function warnUndrawable(image) {
+  if (process.env.NODE_ENV === 'production') return;
+  const kind =
+    typeof image === 'object'
+      ? (image.constructor?.name ?? 'object')
+      : typeof image;
+  if (warnedSources.has(kind)) return;
+  warnedSources.add(kind);
+  const serverSide = typeof image === 'object' && 'id' in image;
+  const article = /^[aeiou]/i.test(kind) ? 'an' : 'a';
+  console.warn(
+    `react-x11: drawImage on the cocoa backend has no pixels for ${article} ${kind}, ` +
+      'and draws nothing. ' +
+      (serverSide
+        ? 'It names an X server-side Picture or Drawable — <image picture>, ' +
+          '<image drawable>, an ntk Picture — and this backend has no X ' +
+          'server to composite from, so those are X11-only. Hand <image src> ' +
+          'the pixels instead: encoded PNG/JPEG bytes, raw RGBA, or an ntk Image.'
+        : 'This backend draws a Surface (react-x11/ntk) or an ntk Image; wrap ' +
+          'raw RGBA as new Image({ width, height, data }).'),
+  );
+}
+
 class LinearGradient {
   constructor(x0, y0, x1, y1) {
     this._coords = [x0, y0, x1, y1];
@@ -953,8 +1047,8 @@ export class CocoaContext2D {
   }
 
   drawImage(image, ...args) {
-    const src = image?._surfaceHandle ?? image?._surface?._surfaceHandle;
-    if (!src) return; // ntk Images/Pictures are not on this backend yet
+    const src = this._sourceHandle(image);
+    if (!src) return;
     const size = this._native.surfaceSize(src);
     let sx = 0;
     let sy = 0;
@@ -990,6 +1084,25 @@ export class CocoaContext2D {
     this._dirty();
   }
 
+  /**
+   * The bitmap a `drawImage` source composites from: a surface's own, an
+   * ntk Image's upload (made on its first draw, see `uploadImage`), or
+   * none. A destroyed surface is none, silently — it had pixels once; any
+   * other source is one this backend cannot draw at all, and development
+   * says so once per kind.
+   */
+  _sourceHandle(image) {
+    if (image == null) return null;
+    if (typeof image === 'object') {
+      if ('_surfaceHandle' in image || image._surface) {
+        return image._surfaceHandle ?? image._surface?._surfaceHandle ?? null;
+      }
+      if (isImagePixels(image)) return uploadImage(this._native, image);
+    }
+    warnUndrawable(image);
+    return null;
+  }
+
   /**
    * `drawImage` as a row memcpy, for the one shape where a copy is all it
    * ever was: a surface composited into another at a translate, whole
@@ -1081,12 +1194,9 @@ export class CocoaContext2D {
 
   putImageData(data, x, y) {
     if (!data?.data) return;
-    const buf = Buffer.isBuffer(data.data)
-      ? data.data
-      : Buffer.from(data.data.buffer ?? data.data);
     this._native.ctxPutImageData(
       this._s(),
-      buf,
+      toBuffer(data.data),
       data.width,
       data.height,
       Math.round(x),