react-x11 2.15.3 → 2.16.1

package/src/settings.js

@@ -0,0 +1,332 @@
+// What an app remembers between launches (#592): a store of JSON values in
+// the per-user directory for this app, read once, written atomically, and
+// coalesced so a slider's stream of changes is one write when it settles.
+//
+//   const settings = createSettings({
+//     appId: 'com.example.Hush',
+//     defaults: { noiseType: 'brown', volume: 0.5, dark: false },
+//   });
+//   const [volume, setVolume] = settings.use('volume');
+//
+// Every app that remembered anything did this by hand — a directory per
+// platform, serialize, write, debounce — and the easy version of it is wrong
+// in three quiet ways: a crash mid-write leaves half a file, a drag writes on
+// every event, and quitting inside the debounce loses the last change.
+//
+// ## Where
+//
+// One JSON file, `settings.json`, in the app's own directory: under
+// `~/Library/Application Support` on macOS and `$XDG_CONFIG_HOME` (`~/.config`)
+// elsewhere. A file rather than `NSUserDefaults` on macOS, so the format and
+// the behaviour are one thing on every platform. The directory is named by
+// the app id, which is a reverse-DNS name like the one `registerApplication`
+// takes — the store does not register anything, it only needs a name no
+// other app is using.
+//
+// ## When it is read and written
+//
+// Read **synchronously**, the first time a value is asked for, so the first
+// render already has what was saved: an asynchronous read would render the
+// defaults and then jump. It is a small file read once. Written
+// **asynchronously**, a quarter second after the last change and at least
+// once a second while changes keep coming, through a temporary file and a
+// rename, which is atomic: the file on disk is always the old one or the new
+// one. Whatever is still waiting is written synchronously when the process
+// exits, and `flush()` writes it now.
+//
+// Two processes of the same app share the file and the last write wins;
+// nothing here watches for another process changing it.
+
+import * as nodeFs from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { useCallback, useSyncExternalStore } from 'react';
+
+/** A reverse-DNS app id: two or more dot-separated elements, the grammar
+ *  `registerApplication` checks, which is also a safe directory name. */
+const APP_ID_RE = /^[A-Za-z_-][A-Za-z0-9_-]*(\.[A-Za-z_-][A-Za-z0-9_-]*)+$/;
+
+/** How long a change waits for the next one, and how long a stream of
+ *  changes may put a write off. */
+const DELAY_MS = 250;
+const MAX_WAIT_MS = 1000;
+
+/** The per-user directory apps keep their settings under, for a platform. */
+export function settingsBaseDir({
+  platform = process.platform,
+  env = process.env,
+  home = homedir(),
+} = {}) {
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Application Support');
+  }
+  if (platform === 'win32') {
+    return env.APPDATA || join(home, 'AppData', 'Roaming');
+  }
+  return env.XDG_CONFIG_HOME || join(home, '.config');
+}
+
+/** One store per file in a process, so a module evaluated twice — a hot
+ *  reload — and two call sites naming the same app share their values
+ *  rather than overwriting each other's writes. */
+const stores = new Map();
+
+/**
+ * The settings store for `appId`: values read from and written to its
+ * `settings.json`, with `defaults` for what was never saved.
+ */
+export function createSettings(options = {}) {
+  const { appId, defaults = {}, directory, fs = nodeFs } = options;
+  if (typeof appId !== 'string' || !APP_ID_RE.test(appId)) {
+    throw new Error(
+      `react-x11: createSettings({ appId: ${JSON.stringify(appId)} }) — the ` +
+        "app id names the app's settings directory, so it is a reverse-DNS " +
+        'name no other app uses: two or more dot-separated elements of ' +
+        '[A-Za-z_-][A-Za-z0-9_-]*, like "com.example.myapp".',
+    );
+  }
+  if (defaults === null || typeof defaults !== 'object') {
+    throw new Error(
+      'react-x11: createSettings({ defaults }) — expected an object of each ' +
+        "setting's value when nothing was saved, like { volume: 0.5 }.",
+    );
+  }
+  const path = join(
+    directory ?? join(settingsBaseDir(), appId),
+    'settings.json',
+  );
+  let store = stores.get(path);
+  if (!store) {
+    store = new SettingsStore(path, fs, options);
+    stores.set(path, store);
+  }
+  // the latest module's defaults win, as a reload's edit to them should
+  store._defaults = { ...defaults };
+  return store.api;
+}
+
+class SettingsStore {
+  constructor(path, fs, { delay = DELAY_MS, maxWait = MAX_WAIT_MS }) {
+    this.path = path;
+    this.fs = fs;
+    this.delay = delay;
+    this.maxWait = maxWait;
+    this._defaults = {};
+    this._fallbacks = new Map(); // key -> the first object fallback asked with
+    this._values = null; // what was saved, read on first use
+    this._listeners = new Set();
+    this._timer = null;
+    this._firstPending = 0; // when the oldest unwritten change was made
+    // Changes are counted, and a write records the count it wrote, so a
+    // change is unsaved until a write *finished* with it in — which is what
+    // the exit path asks, since a write still in flight when the process
+    // exits never finishes.
+    this._version = 0;
+    this._savedVersion = 0;
+    this._writing = null; // the write in flight
+    this._onExit = () => this._flushSync();
+
+    const store = this;
+    this.api = {
+      path,
+      get: (key, fallback) => store.get(key, fallback),
+      set: (key, value) => store.set(key, value),
+      reset: (key) => store.reset(key),
+      flush: () => store.flush(),
+      subscribe: (listener) => store.subscribe(listener),
+      /**
+       * `[value, setValue]` for one setting, like `useState` — and every
+       * component using the same key, in any window, sees the same value.
+       */
+      use(key, fallback) {
+        const subscribe = useCallback(
+          (listener) => store.subscribe(listener),
+          [],
+        );
+        const value = useSyncExternalStore(subscribe, () =>
+          store.get(key, fallback),
+        );
+        const setValue = useCallback(
+          (next) =>
+            store.set(
+              key,
+              typeof next === 'function'
+                ? next(store.get(key, fallback))
+                : next,
+            ),
+          [key, fallback],
+        );
+        return [value, setValue];
+      },
+    };
+  }
+
+  _load() {
+    if (this._values) return this._values;
+    this._values = {};
+    let text;
+    try {
+      text = this.fs.readFileSync(this.path, 'utf8');
+    } catch (err) {
+      // never saved is the ordinary first launch; anything else is worth a line
+      if (err?.code !== 'ENOENT') {
+        console.warn(
+          `react-x11: settings at ${this.path} could not be read ` +
+            `(${err.message}); the defaults stand.`,
+        );
+      }
+      return this._values;
+    }
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        this._values = parsed;
+        return this._values;
+      }
+      throw new Error('not an object');
+    } catch (err) {
+      console.warn(
+        `react-x11: settings at ${this.path} are not a JSON object ` +
+          `(${err.message}); the defaults stand, and the next change ` +
+          'replaces the file.',
+      );
+    }
+    return this._values;
+  }
+
+  get(key, fallback) {
+    const values = this._load();
+    if (Object.hasOwn(values, key)) return values[key];
+    if (Object.hasOwn(this._defaults, key)) return this._defaults[key];
+    // An object literal is a new object every render, and a hook's snapshot
+    // that changes every time it is read never settles: the first one stands.
+    if (fallback !== null && typeof fallback === 'object') {
+      if (!this._fallbacks.has(key)) this._fallbacks.set(key, fallback);
+      return this._fallbacks.get(key);
+    }
+    return fallback;
+  }
+
+  set(key, value) {
+    let text;
+    try {
+      text = JSON.stringify(value);
+    } catch (err) {
+      throw new TypeError(
+        `react-x11: settings.set(${JSON.stringify(key)}) — the value has to ` +
+          `be JSON: ${err.message}`,
+      );
+    }
+    if (text === undefined) {
+      throw new TypeError(
+        `react-x11: settings.set(${JSON.stringify(key)}) — ${typeof value} is ` +
+          'not a value JSON can keep; use reset() to go back to the default.',
+      );
+    }
+    const values = this._load();
+    if (Object.hasOwn(values, key) && values[key] === value) return;
+    this._values = { ...values, [key]: value };
+    this._changed();
+  }
+
+  reset(key) {
+    const values = this._load();
+    if (!Object.hasOwn(values, key)) return;
+    const rest = { ...values };
+    delete rest[key];
+    this._values = rest;
+    this._changed();
+  }
+
+  subscribe(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  get _unsaved() {
+    return this._savedVersion !== this._version;
+  }
+
+  _changed() {
+    for (const listener of [...this._listeners]) listener();
+    if (!this._unsaved) {
+      this._firstPending = Date.now();
+      process.once('exit', this._onExit);
+    }
+    this._version++;
+    clearTimeout(this._timer);
+    const waited = Date.now() - this._firstPending;
+    const wait = Math.max(0, Math.min(this.delay, this.maxWait - waited));
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      this.flush().catch((err) => {
+        console.warn(
+          `react-x11: settings at ${this.path} could not be written ` +
+            `(${err.message}).`,
+        );
+      });
+    }, wait);
+    // a pending write must not be what keeps the process alive
+    this._timer.unref?.();
+  }
+
+  /** Write what is waiting now. Resolves when it is on disk. */
+  async flush() {
+    clearTimeout(this._timer);
+    this._timer = null;
+    // one write at a time, and a change made during one is written after it;
+    // the one before failing is that write's to report, not this one's
+    while (this._writing) await this._writing.catch(() => {});
+    if (!this._unsaved) return;
+    const version = this._version;
+    const text = `${JSON.stringify(this._values, null, 2)}\n`;
+    this._writing = this._write(text).finally(() => {
+      this._writing = null;
+    });
+    await this._writing;
+    this._savedVersion = version;
+    // saved, unless something changed while it was written
+    if (!this._unsaved) process.removeListener('exit', this._onExit);
+  }
+
+  async _write(text) {
+    const fs = this.fs.promises;
+    const temp = `${this.path}.${process.pid}.tmp`;
+    await fs.mkdir(dirname(this.path), { recursive: true });
+    const handle = await fs.open(temp, 'w');
+    try {
+      await handle.writeFile(text);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fs.rename(temp, this.path);
+  }
+
+  /** The exit path, where nothing asynchronous runs any more. */
+  _flushSync() {
+    if (!this._unsaved) return;
+    this._savedVersion = this._version;
+    try {
+      const temp = `${this.path}.${process.pid}.tmp`;
+      this.fs.mkdirSync(dirname(this.path), { recursive: true });
+      this.fs.writeFileSync(temp, `${JSON.stringify(this._values, null, 2)}\n`);
+      this.fs.renameSync(temp, this.path);
+    } catch (err) {
+      console.warn(
+        `react-x11: settings at ${this.path} could not be written on exit ` +
+          `(${err.message}).`,
+      );
+    }
+  }
+}
+
+/** Forget every store — for tests that create stores over temporary
+ *  directories and want the next `createSettings` to read afresh. */
+export function resetSettingsForTests() {
+  for (const store of stores.values()) {
+    clearTimeout(store._timer);
+    process.removeListener('exit', store._onExit);
+  }
+  stores.clear();
+}

package/src/statusnotifier.js

@@ -37,14 +37,55 @@
 //
 // The protocol carries far less about a click than AppKit does. There is no
 // click count, no modifier state, and no item rectangle — `Activate(x, y)`
-// gives the pointer position and nothing else. Those fields are reported as
+// gives a position and nothing else. Those fields are reported as
 // `0`/`false` rather than guessed at, and `docs/desktop.md` says so, because a
 // tray menu that only opens on shift-click is an app built on a field this
 // rung cannot fill. The menu is the portable interaction; `onClick` is the
 // one that degrades.
+//
+// ## The position has no unit
+//
+// The spec says "screen coordinates" and stops, which on a scaled display is
+// two different numbers — and the hosts split between them:
+//
+//   - **X root coordinates, device pixels.** Plasma since 5.27, on purpose:
+//     its xembed-sni-proxy synthesises X clicks from them. GNOME's
+//     AppIndicator extension passes its stage coordinates through, which are
+//     device pixels on X11 and in Wayland's physical layout, the default up
+//     to GNOME 49.
+//   - **The host's own logical pixels.** xfce4-panel, Budgie and LXQt pass
+//     their toolkit's root position through, and Cinnamon sends the icon's
+//     corner over its UI scale. GNOME's stage is in logical pixels from 50,
+//     and before it on Fedora and Debian 13, which switch the layout on
+//     downstream. So did Plasma before 5.27.
+//   - **Not a screen position.** MATE sends the item's corner in its applet's
+//     own window, and snixembed's `Activate` is always `(0, 0)`.
+//
+// Dividing by the scale is right for the first group and halves every click
+// in the second; passing the numbers through is the opposite. So a click is
+// read both ways and the screen picks (`clickReadings`, `clickPoint`):
+//
+//   1. **A reading no monitor holds is not one.** A tray is on the screen,
+//      and a device-pixel host's item at the right or the bottom of it —
+//      where panels put the tray — is off the screen when read as logical
+//      pixels. The common device-pixel click costs nothing more.
+//   2. **Then the pointer.** A host that sends a position sends the
+//      pointer's or its icon's, so one `QueryPointer` names the reading the
+//      click was at.
+//   3. **Otherwise the numbers as sent.** The pointer is somewhere else
+//      because the click was a key, or the connection is XWayland's, which
+//      is told nothing of a pointer over a Wayland panel. As sent is what the
+//      second group needs, and the first group's usual trays were settled at
+//      step 1.
+//
+// What that leaves wrong is a device-pixel host under XWayland whose tray
+// still lands on a monitor read as logical pixels: in the top-left quarter
+// of the screen, or on a desk where it falls on another monitor.
 
 import { loadTransport, sessionBus } from './bus.js';
 import { DbusMenuExport } from './dbusmenuexport.js';
+import { scaleOf } from './scale.js';
+import { screensSnapshot } from './screens.js';
 
 export const WATCHER_NAME = 'org.kde.StatusNotifierWatcher';
 export const WATCHER_PATH = '/StatusNotifierWatcher';
@@ -91,6 +132,43 @@ export function toPixmapArray(image) {
   return [[width, height, out]];
 }
 
+/**
+ * How far from the pointer a click's point may be and still be the click, in
+ * logical pixels. A host that sends the pointer is within a pixel or two of
+ * it, and Cinnamon, which sends its icon's corner, within the icon. A point
+ * further off is taken as sent — which for Cinnamon, a logical-pixel host,
+ * is right anyway.
+ */
+const CLICK_REACH = 64;
+
+/**
+ * A host's `(x, y)` read both ways — as X root coordinates, and as the host's
+ * own logical pixels — keeping the readings some monitor holds. Each is the
+ * point on the screen it names, in device pixels, and what it means in
+ * logical ones. See "The position has no unit" in the header.
+ *
+ * `screens` are device-pixel rects, as `screensSnapshot(app).screens` holds
+ * them; with none known both readings stand, and with neither on a monitor
+ * the host sent something that is not a position.
+ */
+function clickReadings(x, y, scale, screens = []) {
+  const readings = [
+    { device: { x, y }, logical: { x: x / scale, y: y / scale } },
+    { device: { x: x * scale, y: y * scale }, logical: { x, y } },
+  ];
+  if (!screens.length) return readings;
+  // Edges count: a host that sends an icon's far corner can land on one.
+  return readings.filter(({ device: p }) =>
+    screens.some(
+      (m) =>
+        p.x >= m.x &&
+        p.y >= m.y &&
+        p.x <= m.x + m.width &&
+        p.y <= m.y + m.height,
+    ),
+  );
+}
+
 /** `visible: false` is `Passive`, which is how the spec spells "hidden". */
 function statusOf(options) {
   if (options?.visible === false) return 'Passive';
@@ -129,8 +207,13 @@ function iconOf(icon, decode) {
  * in quick succession cannot put two registrations in flight.
  */
 export class StatusNotifierItem {
-  constructor({ getOptions, appId, decodeIcon, onError, slot } = {}) {
+  constructor({ getOptions, app, appId, decodeIcon, onError, slot } = {}) {
     this.getOptions = getOptions ?? (() => null);
+    // The display the tray is on — not for the protocol, which is D-Bus
+    // only, but for a click's position: its scale, its monitors and its
+    // pointer are what put the host's numbers into logical pixels. Null is
+    // no display to ask, and a click's numbers are then passed as sent.
+    this.app = app ?? null;
     this.appId = appId ?? 'react-x11';
     this.decodeIcon = decodeIcon ?? (() => null);
     this.onError = onError ?? (() => {});
@@ -453,27 +536,91 @@ export class StatusNotifierItem {
     if (this.menu) this.menu.update(next.menu ?? []);
   }
 
+  // ------------------------------------------------------------------ click
+
+  /**
+   * A click's `(x, y)` in logical screen pixels — the unit a `<popup>`'s
+   * `x`/`y` and `anchor={{ rect }}` take. Read both ways and settled by the
+   * monitors, then the pointer, then as sent: the header has why.
+   */
+  async clickPoint(x, y) {
+    const scale = scaleOf(this.app);
+    if (scale === 1) return { x, y };
+    const readings = clickReadings(
+      x,
+      y,
+      scale,
+      screensSnapshot(this.app).screens,
+    );
+    if (readings.length === 1) return readings[0].logical;
+    const pointer = readings.length ? await this.queryPointer() : null;
+    if (!pointer) return { x, y };
+    let near = null;
+    let nearest = CLICK_REACH * scale;
+    for (const reading of readings) {
+      const d = Math.hypot(
+        reading.device.x - pointer.x,
+        reading.device.y - pointer.y,
+      );
+      if (d <= nearest) {
+        near = reading;
+        nearest = d;
+      }
+    }
+    return near?.logical ?? { x, y };
+  }
+
+  /**
+   * Where the pointer is on the X screen, in device pixels, or null where
+   * nothing can say: a backend with no X server behind it, a failed request,
+   * a pointer on another screen.
+   */
+  queryPointer() {
+    const X = this.app?.X;
+    const root = X?.display?.screen?.[0]?.root;
+    if (typeof X?.QueryPointer !== 'function' || root == null) {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve) => {
+      try {
+        X.QueryPointer(root, (err, reply) =>
+          resolve(
+            err || !reply?.sameScreen
+              ? null
+              : { x: reply.rootX, y: reply.rootY },
+          ),
+        );
+      } catch {
+        resolve(null);
+      }
+    });
+  }
+
   // --------------------------------------------------------------- protocol
 
   defineItem(dbus) {
     const opts = () => this.options;
     const icon = () => iconOf(opts().icon, this.decodeIcon);
-    const click = (button) => (args) => {
-      // No click count, no modifiers, no item rect: the protocol has none of
-      // them. Reported as zero rather than invented — see the header.
-      opts().onClick?.({
-        button,
-        x: args?.x ?? 0,
-        y: args?.y ?? 0,
-        width: 0,
-        height: 0,
-        clickCount: 1,
-        shift: false,
-        control: false,
-        option: false,
-        command: false,
+    // No click count, no modifiers, no item rect: the protocol has none of
+    // them. Reported as zero rather than invented — see the header. The
+    // position it does have is put into logical pixels first, and the call is
+    // answered once the app has had the click, so a throw in `onClick` still
+    // reaches the host as the error it was.
+    const click = (button) => (args) =>
+      this.clickPoint(args?.x ?? 0, args?.y ?? 0).then(({ x, y }) => {
+        opts().onClick?.({
+          button,
+          x,
+          y,
+          width: 0,
+          height: 0,
+          clickCount: 1,
+          shift: false,
+          control: false,
+          option: false,
+          command: false,
+        });
       });
-    };
 
     return dbus.defineInterface({
       name: ITEM_IFACE,