react-x11 2.15.2 → 2.16.0

package/src/capabilities.js

@@ -0,0 +1,349 @@
+// 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
+// ---------------------------------------------------------------------------
+
+/** The tray on an app that has one of its own, which needs nothing asked. */
+function trayNow(target) {
+  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,
+    });
+  }
+  return null;
+}
+
+async function probeTray({ app } = {}) {
+  const now = trayNow(app ?? soleApp());
+  if (now) return now;
+
+  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
+// ---------------------------------------------------------------------------
+
+/** The Dock tile on an app that has one, which needs nothing asked. */
+function launcherNow(target) {
+  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,
+    });
+  }
+  return null;
+}
+
+async function probeLauncher({ app } = {}) {
+  const now = launcherNow(app ?? soleApp());
+  if (now) return now;
+
+  // 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;
+
+/**
+ * The answer for a capability where it is known without asking anything —
+ * the Cocoa app's own tray and Dock tile — or null where finding out takes a
+ * round trip. What lets `useDesktopCapability` be settled on its first frame
+ * where the answer never needed waiting for.
+ */
+export function capabilityNow(name, { app } = {}) {
+  const target = app ?? soleApp();
+  if (name === 'tray') return trayNow(target);
+  if (name === 'launcher') return launcherNow(target);
+  return null;
+}

package/src/cocoa/app.js

@@ -38,7 +38,9 @@ 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 { CocoaSymbols } from './symbols.js';
 import { CocoaWindow } from './window.js';
 import { decodeKey, modifierMask } from './keymap.js';
 import { loadNative } from './native.js';
@@ -199,6 +201,8 @@ export class CocoaApp {
     // real bridge on the machine — the manager's default loads it only when
     // it is built standalone
     this.fonts = new CocoaFontManager(native);
+    // `<image src={{ symbol }}>`'s names are SF Symbols here (src/symbols.js)
+    this.symbols = new CocoaSymbols(native);
 
     // Native open/save panels (src/cocoa/filepanels.js). Present exactly
     // when the bridge has them (>= 0.5), and its presence is what puts the
@@ -449,6 +453,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.
@@ -628,6 +644,8 @@ export class CocoaApp {
   _unregisterWindow(wnd) {
     this._windows.delete(wnd._key);
     if (this._grabWindow === wnd) this._grabWindow = null;
+    // a popup that took the keyboard and closed is not where keys go next
+    if (this._lastKeyWindow === wnd) this._lastKeyWindow = null;
   }
 
   // --- the pump ------------------------------------------------------------
@@ -789,8 +807,8 @@ export class CocoaApp {
     this._rafQueue = [];
     let soonest = Infinity;
     for (const entry of queue) {
-      // A window whose last flip has not given its back buffer back yet
-      // (threaded mode's fence, `CocoaWindow.frameInFlight`) waits before
+      // A window whose last flip has not reached its layer yet (threaded
+      // mode's fence, `CocoaWindow.frameInFlight`) waits before
       // its clock is asked, or the clock would count a frame that did not
       // run. The release is an event, and the batch it arrives in ticks
       // again.
@@ -861,7 +879,7 @@ export class CocoaApp {
    * paid once, when the batch is done: ten moves and a click that crossed
    * while this thread was busy are one frame, not eleven. Then what a pump
    * tick does: the frames that are due, and the ones a window's visibility
-   * or its back buffer was holding, which an occlusion change or a
+   * or its last flip was holding, which an occlusion change or a
    * `surface-released` in this very batch may just have freed.
    */
   _routeBatch(batch) {
@@ -1077,9 +1095,9 @@ export class CocoaApp {
     // the notch and the scroll, most of a refresh period of nothing.
     //
     // Mostly: a trackpad's momentum lands two in one tick often, and a
-    // second flip inside the refresh draws into the buffer the first one
-    // just took off glass (`CocoaWindow._flippedRecently` says why that
-    // shows). So the rest of a burst lands React's half and leaves the
+    // second flip inside the refresh is a frame the display never shows
+    // (`CocoaWindow._flippedRecently` says what it cost). So the rest of a
+    // burst lands React's half and leaves the
     // paint to the paced frame the scroll already asked for — the model
     // has scrolled, and the next refresh shows all of it.
     if (wnd._flippedRecently()) {
@@ -1188,9 +1206,10 @@ export class CocoaApp {
   /**
    * `surface-released`: a worker's frame took an IOSurface off a layer and
    * the frame that replaced it has committed (windowkit/appkit#52). The
-   * window whose back buffer that was stops waiting on it
-   * (`CocoaWindow._surfaceReleased`), and the tick at the end of this
-   * batch runs the frame it was holding.
+   * window whose buffer that was stops waiting on it, and may draw into it
+   * again once the WindowServer lets go of it too
+   * (`CocoaWindow._surfaceReleased`); the tick at the end of this batch
+   * runs the frame it was holding.
    */
   _routeSurfaceReleased(ev) {
     for (const wnd of this._windows.values()) {

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];
@@ -952,9 +1046,32 @@ export class CocoaContext2D {
     this._dirty();
   }
 
+  /**
+   * An SF Symbol by name, fitted into the rect and centred, in the fill
+   * colour — `ctxDrawSymbol`, `@windowkit/appkit` 0.12.0. Answers false,
+   * drawing nothing, for a name the system does not know and on a bridge
+   * without the verb. `options` are the bridge's: `pointSize`, `weight`,
+   * `scale`, `variableValue`.
+   */
+  drawSymbol(name, x, y, width, height, options) {
+    if (typeof this._native.ctxDrawSymbol !== 'function') return false;
+    this._applyFill();
+    const drawn = this._native.ctxDrawSymbol(
+      this._s(),
+      name,
+      x,
+      y,
+      width,
+      height,
+      options,
+    );
+    if (drawn) this._dirty();
+    return drawn === true;
+  }
+
   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 +1107,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 +1217,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),