react-x11 2.13.0 → 2.15.0

package/src/wayland/framestyle.js

@@ -0,0 +1,257 @@
+// What the desktop says a window frame looks like and does — the part of it
+// a client-side frame needs: which buttons go where, the title's font, and
+// what a click on the titlebar means.
+//
+// GTK reads these from GSettings; anything else reads the same keys through
+// the settings portal, which serves the `org.gnome.desktop.*` schemas beside
+// the four standard appearance values (src/appearance.js reads those, and
+// the frame takes its light or dark from there). The keys, with GNOME's
+// defaults:
+//
+//   org.gnome.desktop.wm.preferences
+//     button-layout                  'appmenu:close'     left:right, comma lists
+//     action-double-click-titlebar   'toggle-maximize'
+//     action-middle-click-titlebar   'none'
+//     action-right-click-titlebar    'menu'
+//   org.gnome.desktop.interface
+//     font-name                      'Adwaita Sans 11'   a Pango description
+//     text-scaling-factor            1.0
+//
+// The title is drawn in the *interface* font, bold, because that is what a
+// libadwaita headerbar does: measured against one on a desktop whose
+// `font-name` is 'Sans 23', its title's cap height is a 23pt DejaVu Sans
+// Bold's. `titlebar-font` is for frames the window manager draws (Xwayland
+// windows); a client frame that used it would not match the GTK apps beside
+// it.
+//
+// Where there is no portal — another desktop, a test — the defaults stand.
+// They are GNOME's, so a frame drawn to them is the frame GTK would draw.
+
+import { EventEmitter } from 'node:events';
+import { sessionBus } from '../bus.js';
+import { desktopIntegrationEnabled } from '../desktopintegration.js';
+
+const PORTAL_NAME = 'org.freedesktop.portal.Desktop';
+const PORTAL_PATH = '/org/freedesktop/portal/desktop';
+const SETTINGS_IFACE = 'org.freedesktop.portal.Settings';
+const WM = 'org.gnome.desktop.wm.preferences';
+const IFACE = 'org.gnome.desktop.interface';
+const NAMESPACES = [WM, IFACE];
+
+export const DEFAULTS = Object.freeze({
+  buttonLayout: 'appmenu:close',
+  fontName: 'Adwaita Sans 11',
+  textScaling: 1,
+  doubleClick: 'toggle-maximize',
+  middleClick: 'none',
+  rightClick: 'menu',
+});
+
+/** The buttons a client frame can draw; `appmenu`, `icon`, `spacer` have
+ * nothing to show here and are dropped. */
+const BUTTONS = new Set(['close', 'minimize', 'maximize']);
+
+/**
+ * `'icon,menu:minimize,maximize,close'` → `{ left: [], right: ['minimize',
+ * 'maximize', 'close'] }`. A layout with no colon is all on the left, as in
+ * GTK; a button named twice is drawn once, where it first appears.
+ */
+export function parseButtonLayout(value) {
+  const [left = '', right = ''] = String(value ?? '').split(':');
+  const seen = new Set();
+  const side = (list) =>
+    list
+      .split(',')
+      .map((b) => b.trim())
+      .filter((b) => {
+        if (!BUTTONS.has(b) || seen.has(b)) return false;
+        seen.add(b);
+        return true;
+      });
+  return { left: side(left), right: side(right) };
+}
+
+const WEIGHTS = {
+  thin: 100,
+  ultralight: 200,
+  'ultra-light': 200,
+  extralight: 200,
+  'extra-light': 200,
+  light: 300,
+  semilight: 350,
+  'semi-light': 350,
+  book: 380,
+  regular: 400,
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  'semi-bold': 600,
+  demibold: 600,
+  'demi-bold': 600,
+  bold: 700,
+  ultrabold: 800,
+  'ultra-bold': 800,
+  extrabold: 800,
+  'extra-bold': 800,
+  heavy: 900,
+  black: 900,
+};
+const STYLE_WORDS = new Set([
+  'italic',
+  'oblique',
+  'roman',
+  'small-caps',
+  'condensed',
+  'semi-condensed',
+  'extra-condensed',
+  'ultra-condensed',
+  'expanded',
+  'semi-expanded',
+  'extra-expanded',
+  'ultra-expanded',
+]);
+
+/**
+ * A Pango font description — `"Adwaita Sans Bold 11"`, `"Sans 23"`,
+ * `"DejaVu Sans Condensed Italic 12px"` — as `{ family, size, unit, weight,
+ * italic }`. Style words are read off the end until one is not a style
+ * word; what remains is the family (the first of a comma list).
+ */
+export function parseFontName(value) {
+  const words = String(value ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  let size = null;
+  let unit = 'pt';
+  const last = words.at(-1);
+  if (last && /^\d+(\.\d+)?(px)?$/i.test(last)) {
+    if (/px$/i.test(last)) unit = 'px';
+    size = parseFloat(last);
+    words.pop();
+  }
+  let weight = 400;
+  let italic = false;
+  while (words.length > 1) {
+    const w = words.at(-1).toLowerCase();
+    if (Object.hasOwn(WEIGHTS, w)) weight = WEIGHTS[w];
+    else if (STYLE_WORDS.has(w)) {
+      if (w === 'italic' || w === 'oblique') italic = true;
+    } else break;
+    words.pop();
+  }
+  const family = words.join(' ').split(',')[0].trim() || 'sans-serif';
+  return { family, size: size ?? 11, unit, weight, italic };
+}
+
+/** The title's font: the interface font, bold, at 96dpi times the scaling
+ * factor — in logical pixels. */
+export function titleFont(style = DEFAULTS) {
+  const f = parseFontName(style.fontName);
+  const scaling = Number(style.textScaling) > 0 ? Number(style.textScaling) : 1;
+  const px = (f.unit === 'px' ? f.size : (f.size * 96) / 72) * scaling;
+  return { family: f.family, size: px, weight: 700 };
+}
+
+/** The two namespaces `ReadAll` answered, as a frame style. */
+export function fromPortal(all) {
+  const wm = all?.[WM] ?? {};
+  const iface = all?.[IFACE] ?? {};
+  const str = (v, d) => (typeof v === 'string' && v ? v : d);
+  const num = (v, d) => (typeof v === 'number' && v > 0 ? v : d);
+  return Object.freeze({
+    buttonLayout: str(wm['button-layout'], DEFAULTS.buttonLayout),
+    fontName: str(iface['font-name'], DEFAULTS.fontName),
+    textScaling: num(iface['text-scaling-factor'], DEFAULTS.textScaling),
+    doubleClick: str(wm['action-double-click-titlebar'], DEFAULTS.doubleClick),
+    middleClick: str(wm['action-middle-click-titlebar'], DEFAULTS.middleClick),
+    rightClick: str(wm['action-right-click-titlebar'], DEFAULTS.rightClick),
+  });
+}
+
+/**
+ * The desktop's frame style, followed: `value` is always usable (the
+ * defaults until the portal answers), and 'change' fires when it moves.
+ */
+export class FrameStyle extends EventEmitter {
+  constructor() {
+    super();
+    this.value = DEFAULTS;
+    /** 'portal' once the portal answered; 'defaults' until then, or for good */
+    this.source = 'defaults';
+    this._stop = null;
+  }
+
+  /**
+   * Read once and subscribe. Never throws: no portal means the defaults.
+   * The order is appearance.js's, for its reasons — the match rule and the
+   * handler go on before the read, so a change landing mid-read is caught,
+   * and reads are sequenced so an older answer never overwrites a newer one.
+   * The bus ref is released at the end: the subscription outlives it, and
+   * holding it would keep the process alive for as long as the frame cared
+   * what the desktop said.
+   */
+  async start() {
+    if (!desktopIntegrationEnabled()) return this;
+    let ref = null;
+    try {
+      ref = await sessionBus();
+    } catch {
+      return this;
+    }
+    if (!ref) return this;
+    let sub = null;
+    try {
+      sub = await ref.bus.watch(
+        `type='signal',sender='${PORTAL_NAME}',` +
+          `interface='${SETTINGS_IFACE}',member='SettingChanged'`,
+      );
+      let started = 0;
+      let published = 0;
+      const bus = ref.bus;
+      const refresh = async () => {
+        const mine = ++started;
+        const all = await bus.invoke(
+          {
+            destination: PORTAL_NAME,
+            path: PORTAL_PATH,
+            interface: SETTINGS_IFACE,
+            member: 'ReadAll',
+            signature: 'as',
+            body: [NAMESPACES],
+          },
+          { timeout: 5_000 },
+        );
+        if (!all || mine <= published) return;
+        published = mine;
+        this.value = fromPortal(all);
+        this.source = 'portal';
+        this.emit('change', this.value);
+      };
+      const key = bus.mangle(PORTAL_PATH, SETTINGS_IFACE, 'SettingChanged');
+      const onSignal = ([namespace]) => {
+        if (!NAMESPACES.includes(namespace)) return;
+        refresh().catch(() => {
+          // the portal went away mid-session; the last answer stands
+        });
+      };
+      bus.signals.on(key, onSignal);
+      const subscription = sub;
+      this._stop = () => {
+        bus.signals.off?.(key, onSignal);
+        subscription?.remove().catch(() => {});
+      };
+      await refresh();
+    } catch {
+      await sub?.remove().catch(() => {});
+    } finally {
+      await ref.release();
+    }
+    return this;
+  }
+
+  stop() {
+    this._stop?.();
+    this._stop = null;
+  }
+}

package/src/wayland/framewatch.js

@@ -0,0 +1,190 @@
+// Noticing that the compositor has stopped showing this surface.
+//
+// After the first present the frame loop has exactly one source of liveness:
+// `wl_surface.frame`, which a compositor is entitled never to send to a
+// surface it is not showing — occluded, on another workspace, minimised, the
+// screen locked. That is the right behaviour to drive a client with (drawing
+// into a surface nobody sees is work for nothing) and it has one hole: a
+// callback that never fires is not an error. Nothing rejects, nothing throws,
+// the frame stays armed, and every later `_armFrame()` returns at its guard.
+// The app above goes on re-rendering into a tree that reaches no screen, and
+// from outside the process that is indistinguishable from a hang (#567).
+//
+// So the loop is watched. A frame callback outstanding longer than
+// `REACT_X11_WAYLAND_FRAME_STALL_MS` (2s; `0` turns the watch off) is taken
+// as "the compositor has parked us", which is
+//
+//   - **said once on stderr, in development**, when the window still had
+//     something to draw — the line that the debugging session behind #567
+//     would have ended at; and
+//   - **published**, as `useWindowState().presenting`, so an app can stop
+//     animating and simulating instead of feeding a loop nobody is turning.
+//
+// Nothing here paces or re-arms anything: the parked callback is still queued
+// with the compositor and fires the moment the surface is shown again, which
+// is what un-parks the loop and flips `presenting` back. A timer that painted
+// anyway would be drawing into a surface nobody sees, which is the thing the
+// frame callback is right about.
+
+import { writeSync } from 'node:fs';
+
+const DEV = process.env.NODE_ENV !== 'production';
+
+/** How long a frame callback may be outstanding before the loop counts as
+ *  parked, in milliseconds. `0` — or anything that is not a number — turns
+ *  the watch off entirely: no timer, no warning, `presenting` always true. */
+export const FRAME_STALL_MS = (() => {
+  const raw = process.env.REACT_X11_WAYLAND_FRAME_STALL_MS;
+  if (raw === undefined || raw === '') return 2000;
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms >= 0 ? ms : 0;
+})();
+
+/**
+ * The one line. It names the three things the symptom does not: that this is
+ * the compositor's decision and not a crash, that the window is the thing to
+ * look at, and where to read the state from in code.
+ */
+export function stallMessage(id, ms) {
+  return (
+    `react-x11 (wayland): window ${id} has had a frame callback outstanding ` +
+    `for ${(ms / 1000).toFixed(1)}s with a repaint waiting — the compositor ` +
+    'is not showing this surface (covered, on another workspace, minimised, ' +
+    'or the screen is locked), so nothing this app draws will reach the ' +
+    'screen until it does. The app is not hung. Read it in the tree as ' +
+    'useWindowState().presenting, which is false until the next frame ' +
+    'callback arrives. Said once per window; ' +
+    'REACT_X11_WAYLAND_FRAME_STALL_MS=0 turns it off.\n'
+  );
+}
+
+// Synchronous, like the frame trace in backendwindow.js and for the same
+// reason: Bun buffers `process.stderr` to a file, and a buffer is what a
+// SIGINT leaves behind — which is exactly how a run that looks hung ends.
+const toStderr = (message) => writeSync(2, message);
+
+/**
+ * One window's frame-callback liveness.
+ *
+ * Three calls from the frame loop, and they are the whole interface:
+ * `waiting()` when a `wl_surface.frame` has been asked for, `arrived()` when
+ * one comes back, `idle()` when the loop stops waiting for one at all (a
+ * rejected request, a closing connection). `presenting` is the answer, and
+ * `onChange` fires only when it turns over.
+ *
+ * The timers are injected so the policy above can be tested without a
+ * compositor, a GPU, or two seconds of wall clock.
+ */
+export class FrameWatch {
+  /**
+   * @param {object} opts
+   * @param {number|string} [opts.id] the window's id, for the message
+   * @param {number} [opts.stallMs] how long is too long
+   * @param {() => boolean} [opts.pending] is a repaint waiting? — only then
+   *   is the silence worth a line on stderr
+   * @param {(presenting: boolean) => void} [opts.onChange]
+   * @param {(message: string) => void} [opts.warn]
+   * @param {boolean} [opts.dev] whether to warn at all
+   */
+  constructor({
+    id = 0,
+    stallMs = FRAME_STALL_MS,
+    pending = () => false,
+    onChange = () => {},
+    warn = toStderr,
+    dev = DEV,
+    setTimer = (fn, ms) => {
+      const t = setTimeout(fn, ms);
+      // a diagnostic must never be the reason a process stays up
+      t.unref?.();
+      return t;
+    },
+    clearTimer = (t) => clearTimeout(t),
+  } = {}) {
+    this.id = id;
+    this.stallMs = stallMs;
+    this.presenting = true;
+    this._pending = pending;
+    this._onChange = onChange;
+    this._warn = warn;
+    this._dev = dev;
+    this._setTimer = setTimer;
+    this._clearTimer = clearTimer;
+    this._timer = null;
+    this._warned = false;
+    this._stopped = false;
+  }
+
+  /** A frame callback has been asked for. */
+  waiting() {
+    // An already-running timer is left alone: it measures the age of the
+    // oldest outstanding request, which is the one that matters.
+    if (this._stopped || this._timer || !(this.stallMs > 0)) return;
+    this._timer = this._setTimer(() => {
+      this._timer = null;
+      this._stall();
+    }, this.stallMs);
+  }
+
+  /** A frame callback arrived: the compositor is showing this surface. */
+  arrived() {
+    this._disarm();
+    this._publish(true);
+  }
+
+  /** Nothing is outstanding — a rejected request, a frame that drew nothing
+   *  and asked for no other. Says nothing about whether we are being shown. */
+  idle() {
+    this._disarm();
+  }
+
+  /**
+   * A repaint was asked for while a frame was already in flight.
+   *
+   * There is nothing to arm — the flight is armed, and the request will ride
+   * it — but if that flight is the compositor's silence then this is the
+   * moment the app starts drawing for nobody, and it is the other order the
+   * bug arrives in: a window can park while it has nothing to draw (nothing
+   * to warn about) and be given work a minute later, by which time the
+   * deadline has come and gone.
+   */
+  workArrived() {
+    if (this._stopped || this.presenting) return;
+    this._maybeWarn();
+  }
+
+  /** The window is going away. */
+  stop() {
+    this._stopped = true;
+    this._disarm();
+  }
+
+  _disarm() {
+    if (this._timer === null) return;
+    this._clearTimer(this._timer);
+    this._timer = null;
+  }
+
+  _stall() {
+    if (this._stopped) return;
+    this._maybeWarn();
+    this._publish(false);
+  }
+
+  /**
+   * The line, once per window, and only where the app had something to draw:
+   * a window that is simply idle is not being let down by anyone, and a
+   * warning there would fire on every app that comes to rest.
+   */
+  _maybeWarn() {
+    if (!this._dev || this._warned || !this._pending()) return;
+    this._warned = true;
+    this._warn(stallMessage(this.id, this.stallMs));
+  }
+
+  _publish(presenting) {
+    if (this.presenting === presenting) return;
+    this.presenting = presenting;
+    this._onChange(presenting);
+  }
+}