react-x11 1.2.0 → 2.0.0

package/src/decorations.js

@@ -0,0 +1,486 @@
+// The two decorations that are not a colour: the gradient behind a box
+// (`backgroundImage`) and the shadow under it (`boxShadow`). Both are pure
+// here — strings in, numbers out — so the renderer half in `nodes.js` is
+// only geometry and compositing, and the parsing can be tested without a
+// server (issue #345).
+//
+// ## Why they are strings
+//
+// Every other paint property in this vocabulary is a number or a colour,
+// and an object (`{ from, to, angle }`) would have been the house shape.
+// These two are strings because a gradient and a shadow are the two style
+// values people already know by heart in CSS's spelling, because a state
+// block wants to overwrite the whole decoration at once rather than merge
+// half an object into it, and because `linear-gradient(#2b5876, #4e4376)`
+// pastes out of a design tool. Parsing is memoized per string, so the cost
+// of the choice is one Map lookup per painted frame.
+//
+// ## What is deliberately not here
+//
+// - `radial-gradient` / `conic-gradient`: RENDER has both and ntk exposes
+//   them, but CSS's sizing keywords (`closest-side`, `farthest-corner`, an
+//   ellipse with two radii and a position) are most of the work and none of
+//   the demand. `linear-gradient` is what a header, a card and a selected
+//   row are made of.
+// - `inset` shadows: a different drawing (the coverage is the box *minus*
+//   the blurred rect) and a different damage story, since an inset shadow
+//   never leaves the node. Rejected loudly rather than ignored — see
+//   `parseBoxShadow` — because silently painting an outer shadow where an
+//   inner one was asked for is a bug the author cannot see the cause of.
+// - `textShadow`: per glyph, through the glyph cache, and much rarer in a
+//   desktop UI.
+
+/** A number, with or without the `px` CSS wants and this vocabulary does not. */
+const LENGTH = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:px)?$/i;
+/** …and the same thing as a percentage, which colour stops also take. */
+const PERCENT = /^[+-]?(?:\d+\.?\d*|\.\d+)%$/;
+const ANGLE = /^([+-]?(?:\d+\.?\d*|\.\d+))(deg|grad|rad|turn)$/i;
+
+const TO_ANGLE = { top: 0, right: 90, bottom: 180, left: 270 };
+const VERTICAL = new Set(['top', 'bottom']);
+const HORIZONTAL = new Set(['left', 'right']);
+
+/**
+ * Split on `,` or on whitespace, but only at the top level: a stop is
+ * `rgba(0, 0, 0, .4)` as often as it is `#333`, and every naive split on
+ * this vocabulary gets that wrong.
+ */
+function splitTop(text, byComma) {
+  const out = [];
+  let depth = 0;
+  let start = 0;
+  const push = (end) => {
+    const piece = text.slice(start, end).trim();
+    if (byComma || piece) out.push(piece);
+  };
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if (
+      depth === 0 &&
+      (byComma ? ch === ',' : ch === ' ' || ch === '\t')
+    ) {
+      push(i);
+      start = i + 1;
+    }
+  }
+  push(text.length);
+  return out;
+}
+
+const number = (text) => parseFloat(text);
+
+function toDegrees(value, unit) {
+  switch (unit.toLowerCase()) {
+    case 'deg':
+      return value;
+    case 'grad':
+      return (value * 360) / 400;
+    case 'rad':
+      return (value * 180) / Math.PI;
+    default:
+      return value * 360; // turn
+  }
+}
+
+/**
+ * `linear-gradient(...)` → `{ angle, corner, stops }`, or null for `none`
+ * and for a value that is not a gradient at all.
+ *
+ * `angle` is CSS's: degrees clockwise from "up", so `180deg` is `to bottom`,
+ * which is also the default when a value names no direction. `corner` is
+ * `'top right'` and friends, which cannot become an angle until the box is
+ * known — the corner keywords are defined so that the gradient line is
+ * perpendicular to the box's *other* diagonal, and that depends on the
+ * aspect ratio (see `linearGradientGeometry`).
+ *
+ * Stops keep their authored position (`{ value, unit }`) or `null` for one
+ * that was left out; distributing those needs the gradient line's length,
+ * which is again the box's business.
+ *
+ * Throws on a malformed value rather than dropping it: a gradient that does
+ * not paint is a blank panel, and "why is my header empty" is a much worse
+ * afternoon than an error naming the property.
+ */
+export function parseLinearGradient(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!text || text === 'none') return null;
+  const open = text.indexOf('(');
+  const name = open === -1 ? text : text.slice(0, open).trim();
+  if (name !== 'linear-gradient') {
+    throw new Error(
+      `react-x11: backgroundImage ${JSON.stringify(value)} is not supported ` +
+        "(expected linear-gradient(…) or 'none'). url() images belong on " +
+        '<image src>, and a radial or conic gradient on a <canvas onDraw>.',
+    );
+  }
+  if (!text.endsWith(')')) {
+    throw new Error(
+      `react-x11: backgroundImage ${JSON.stringify(value)} is missing its ` +
+        'closing parenthesis',
+    );
+  }
+  const parts = splitTop(text.slice(open + 1, -1), true);
+  let angle = null;
+  let corner = null;
+  const first = parts[0] ?? '';
+  const asAngle = ANGLE.exec(first);
+  if (asAngle) {
+    angle = toDegrees(number(asAngle[1]), asAngle[2]);
+    parts.shift();
+  } else if (first.startsWith('to ') || first === 'to') {
+    const sides = splitTop(first.slice(2), false);
+    corner = readSides(sides, value);
+    if (typeof corner === 'number') {
+      angle = corner;
+      corner = null;
+    }
+    parts.shift();
+  }
+  const stops = parts.map((part) => readStop(part, value));
+  if (stops.length < 2) {
+    throw new Error(
+      `react-x11: backgroundImage ${JSON.stringify(value)} needs at least ` +
+        'two colour stops',
+    );
+  }
+  return { angle: angle ?? (corner ? null : TO_ANGLE.bottom), corner, stops };
+}
+
+/** `to bottom` → 180; `to bottom right` → the corner it names. */
+function readSides(sides, value) {
+  const bad = () =>
+    new Error(
+      `react-x11: backgroundImage ${JSON.stringify(value)} has an unusable ` +
+        "direction (expected 'to top', 'to bottom right', … or an angle " +
+        "like '135deg')",
+    );
+  if (sides.length === 1) {
+    const one = TO_ANGLE[sides[0]];
+    if (one === undefined) throw bad();
+    return one;
+  }
+  if (sides.length !== 2) throw bad();
+  const [a, b] = sides;
+  const vertical = VERTICAL.has(a) ? a : VERTICAL.has(b) ? b : null;
+  const horizontal = HORIZONTAL.has(a) ? a : HORIZONTAL.has(b) ? b : null;
+  if (!vertical || !horizontal) throw bad();
+  return `${vertical} ${horizontal}`;
+}
+
+/** `#333`, `$accent 40%`, `rgba(0, 0, 0, .4) 12px`. */
+function readStop(part, value) {
+  if (!part) {
+    throw new Error(
+      `react-x11: backgroundImage ${JSON.stringify(value)} has an empty ` +
+        'colour stop',
+    );
+  }
+  const pieces = splitTop(part, false);
+  const last = pieces[pieces.length - 1];
+  if (pieces.length === 1 && (PERCENT.test(last) || LENGTH.test(last))) {
+    // CSS's *colour hint* — a bare position between two stops that moves the
+    // midpoint of the blend. It is a curve, not a stop, and RENDER has no
+    // way to express one; two stops either side say the same thing.
+    throw new Error(
+      `react-x11: backgroundImage ${JSON.stringify(value)} uses a colour ` +
+        `hint ("${last}"), which is not supported — name the colour at that ` +
+        'position instead.',
+    );
+  }
+  if (pieces.length > 1 && (PERCENT.test(last) || LENGTH.test(last))) {
+    pieces.pop();
+    return {
+      color: pieces.join(' '),
+      position: { value: number(last), unit: PERCENT.test(last) ? '%' : 'px' },
+    };
+  }
+  return { color: part, position: null };
+}
+
+/**
+ * Where the gradient line runs for this box, and the stops along it — the
+ * whole of what `ctx.createLinearGradient` and `addColorStop` need.
+ *
+ * CSS's geometry, which is not the obvious one: the line passes through the
+ * box's centre at the given angle, and its length is the box's *projection*
+ * onto it (`|w·sinθ| + |h·cosθ|`), so that the two corners nearest each end
+ * land exactly on the end colours. That is what makes `135deg` on a wide
+ * header look the way it does in a browser instead of running out a third of
+ * the way across.
+ *
+ * ### The padding, and why it is not cosmetic
+ *
+ * Past its last stop an XRender gradient is **transparent**, not clamped:
+ * `RepeatPad` is a picture attribute the gradient path does not set today
+ * (sidorares/ntk#271, and the `TODO` in ntk's own `CanvasGradient`). CSS and
+ * canvas both clamp. So the line is extended by `pad` device pixels at each
+ * end and the stop offsets are remapped onto the longer line, with the end
+ * colours pinned at 0 and 1 — which *is* pad semantics, expressed in stops.
+ * Two pixels would do for the float noise at a corner; the width here also
+ * covers a caller that rounds the rect it fills after asking for the
+ * geometry.
+ *
+ * Note that this cannot be caught by a pixel test against the in-process X
+ * server: node-x11's RENDER pads by construction (`gradientAt` clamps to the
+ * edge stops), where a real server does not. `test/decorations.test.js`
+ * asserts the stops instead, which is the part that is ours.
+ *
+ * Returns null for a box with no area, which has no gradient line at all.
+ */
+export function linearGradientGeometry(spec, rect, pad = 4) {
+  const { width, height } = rect;
+  if (!(width > 0) || !(height > 0)) return null;
+  const degrees = spec.corner
+    ? cornerAngle(spec.corner, width, height)
+    : spec.angle;
+  const theta = (degrees * Math.PI) / 180;
+  // 0° points up and angles run clockwise, so the direction vector is
+  // (sin, -cos) in a coordinate system whose y grows downwards
+  const dx = Math.sin(theta);
+  const dy = -Math.cos(theta);
+  const length = Math.abs(width * dx) + Math.abs(height * dy);
+  if (!(length > 0)) return null;
+  const cx = rect.x + width / 2;
+  const cy = rect.y + height / 2;
+  const half = length / 2;
+  const offsets = resolveStopOffsets(spec.stops, length);
+  const total = length + pad * 2;
+  const stops = [];
+  if (pad > 0) stops.push([0, spec.stops[0].color]);
+  for (let i = 0; i < spec.stops.length; i++) {
+    stops.push([(pad + offsets[i] * length) / total, spec.stops[i].color]);
+  }
+  if (pad > 0) stops.push([1, spec.stops[spec.stops.length - 1].color]);
+  return {
+    x0: cx - dx * (half + pad),
+    y0: cy - dy * (half + pad),
+    x1: cx + dx * (half + pad),
+    y1: cy + dy * (half + pad),
+    stops,
+  };
+}
+
+/**
+ * The magic angle behind `to bottom right`: the gradient line is turned so
+ * that a perpendicular through it passes through the two *other* corners, so
+ * a square gives 45° and a wide box tends towards `to right`.
+ */
+function cornerAngle(corner, width, height) {
+  const base = (Math.atan2(width, height) * 180) / Math.PI;
+  switch (corner) {
+    case 'top right':
+      return base;
+    case 'bottom right':
+      return 180 - base;
+    case 'bottom left':
+      return 180 + base;
+    default: // top left
+      return 360 - base;
+  }
+}
+
+/**
+ * Stop positions as fractions of the gradient line, CSS's rules: a missing
+ * first is 0 and a missing last is 1, a run of missing ones is spread evenly
+ * between the neighbours that do have a position, and a position that goes
+ * backwards is pulled up to the largest so far (which is how a hard colour
+ * break — two stops at the same offset — stays expressible).
+ */
+function resolveStopOffsets(stops, length) {
+  const out = stops.map(({ position }) => {
+    if (!position) return null;
+    return position.unit === '%'
+      ? position.value / 100
+      : position.value / length;
+  });
+  if (out[0] === null) out[0] = 0;
+  if (out[out.length - 1] === null) out[out.length - 1] = 1;
+  for (let i = 1; i < out.length; i++) {
+    if (out[i] !== null) continue;
+    let end = i + 1;
+    while (out[end] === null) end++;
+    const from = out[i - 1];
+    const step = (out[end] - from) / (end - i + 1);
+    for (let j = i; j < end; j++) out[j] = from + step * (j - i + 1);
+    i = end - 1;
+  }
+  let highest = 0;
+  for (let i = 0; i < out.length; i++) {
+    highest = out[i] = Math.max(highest, Math.min(1, Math.max(0, out[i])));
+  }
+  return out;
+}
+
+/**
+ * `boxShadow` → a list of `{ dx, dy, blur, spread, color }`, painted in the
+ * order CSS paints them: first in the list is nearest the front, so the
+ * renderer draws the list back to front.
+ *
+ * `color` may be null, which is CSS's `currentColor` — the node's own ink,
+ * which the caller resolves because only it knows the cascade.
+ *
+ * Throws on `inset` and on anything unparseable; see the note at the top of
+ * this file for why a shadow that silently does the wrong thing is worse
+ * than one that refuses.
+ */
+export function parseBoxShadow(value) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!text || text === 'none') return null;
+  return splitTop(text, true).map((one) => readShadow(one, value));
+}
+
+function readShadow(part, value) {
+  const bad = (why) =>
+    new Error(
+      `react-x11: boxShadow ${JSON.stringify(value)} ${why} (expected ` +
+        "'<x> <y> [blur] [spread] [colour]', e.g. '0 2px 8px rgba(0, 0, 0, .4)')",
+    );
+  const pieces = splitTop(part, false);
+  if (!pieces.length) throw bad('has an empty shadow');
+  if (pieces.some((p) => p.toLowerCase() === 'inset')) {
+    throw new Error(
+      `react-x11: boxShadow ${JSON.stringify(value)} asks for an inset ` +
+        'shadow, which is not implemented — only outer shadows are. An ' +
+        'inner glow can be drawn with an inset border or a <canvas onDraw>.',
+    );
+  }
+  const lengths = [];
+  let color = null;
+  for (const piece of pieces) {
+    if (LENGTH.test(piece)) {
+      if (lengths.length === 4) throw bad('has more than four lengths');
+      lengths.push(number(piece));
+      continue;
+    }
+    if (color !== null) throw bad(`has more than one colour ("${piece}")`);
+    color = piece;
+  }
+  if (lengths.length < 2) throw bad('needs an x and a y offset');
+  const [dx, dy, blur = 0, spread = 0] = lengths;
+  if (blur < 0) throw bad('has a negative blur radius');
+  return { dx, dy, blur, spread, color };
+}
+
+/**
+ * The gaussian a CSS blur radius means, and the room it needs.
+ *
+ * CSS defines the blur radius as *twice* the standard deviation, and ntk's
+ * `Picture.setBlurFilter(size, sigma)` takes the convolution kernel's edge
+ * length rather than a radius — so the two names that look like they match
+ * are the two that must not be passed to each other. The kernel is cut at
+ * 3σ, where the gaussian is down to 1% and the truncation is invisible;
+ * `pad` is the same distance, and it is what stops the blur clipping square
+ * against the edge of the surface it was rendered into.
+ *
+ * `MAX_KERNEL` bounds a pathological value: the server convolves N² taps per
+ * pixel, so a 200px blur asked for by accident would otherwise be a frame
+ * that never lands.
+ */
+const MAX_KERNEL = 61;
+
+export function blurKernel(blur) {
+  const sigma = blur / 2;
+  const reach = Math.ceil(3 * sigma);
+  const size = Math.min(MAX_KERNEL, 2 * reach + 1);
+  return { sigma, size, pad: (size - 1) / 2 + 1 };
+}
+
+/**
+ * How far outside the node's own box this shadow list reaches, in device
+ * pixels — the damage inflation, and the reason a shadow is not just a
+ * colour. Symmetric on purpose: a shadow offset down and right claims the
+ * same slack above and left, which costs a few pixels of repaint and saves
+ * every caller from carrying four numbers around.
+ */
+export function shadowExtent(shadows) {
+  let extent = 0;
+  for (const s of shadows ?? []) {
+    const reach =
+      Math.max(Math.abs(s.dx), Math.abs(s.dy)) +
+      s.spread +
+      (s.blur > 0 ? blurKernel(s.blur).pad : 0);
+    if (reach > extent) extent = reach;
+  }
+  return Math.ceil(Math.max(0, extent));
+}
+
+// --- memoized parsing ------------------------------------------------------
+//
+// A style value is a string that is usually the same string as last frame —
+// a hoisted style, a theme token resolved to the same colour — so the parse
+// is keyed on it and never repeated. Failures are cached as `null` too:
+// `validateStyle` has already thrown for them in development, and a frame in
+// production must not re-throw once per node per frame for a value nothing
+// is going to fix mid-run.
+
+const MAX_CACHE = 256;
+const gradients = new Map();
+const shadows = new Map();
+
+function memoize(cache, key, parse) {
+  if (cache.has(key)) return cache.get(key);
+  let parsed = null;
+  try {
+    parsed = parse(key);
+  } catch {
+    parsed = null;
+  }
+  if (cache.size >= MAX_CACHE) cache.clear();
+  cache.set(key, parsed);
+  return parsed;
+}
+
+/**
+ * The display scale's route into these two values, which is unlike every
+ * other style length's: `boxShadow` and `backgroundImage` are *strings*,
+ * so the multiply at the style funnel (styles.js, scaleResolvedStyle)
+ * cannot reach the numbers inside them — and the parses are memoized on
+ * the raw string, so the scaled result has to be memoized beside it
+ * rather than patched after. The scale rides into the memo key.
+ */
+function scaleShadows(specs, scale) {
+  if (!specs || scale === 1) return specs;
+  return specs.map((s) => ({
+    ...s,
+    dx: s.dx * scale,
+    dy: s.dy * scale,
+    blur: s.blur * scale,
+    spread: s.spread * scale,
+  }));
+}
+
+function scaleGradient(spec, scale) {
+  if (!spec || scale === 1) return spec;
+  let stops = spec.stops;
+  if (stops?.some((stop) => stop.position?.unit === 'px')) {
+    stops = stops.map((stop) =>
+      stop.position?.unit === 'px'
+        ? {
+            ...stop,
+            position: { ...stop.position, value: stop.position.value * scale },
+          }
+        : stop,
+    );
+    return { ...spec, stops };
+  }
+  return spec;
+}
+
+/** `parseLinearGradient`, memoized and non-throwing: the paint path's door.
+ *  `scale` converts any `px` stop positions to device pixels — percentages
+ *  and angles mean the same thing at any density. */
+export const gradientSpec = (value, scale = 1) =>
+  memoize(gradients, scale === 1 ? value : `${scale}\u0000${value}`, () =>
+    scaleGradient(parseLinearGradient(value), scale),
+  );
+
+/** `parseBoxShadow`, memoized and non-throwing. `scale` converts the
+ *  offsets, the blur and the spread to device pixels. */
+export const shadowSpecs = (value, scale = 1) =>
+  memoize(shadows, scale === 1 ? value : `${scale}\u0000${value}`, () =>
+    scaleShadows(parseBoxShadow(value), scale),
+  );

package/src/desktopsettings.js

@@ -0,0 +1,209 @@
+// The desktop's interaction settings: how fast a caret blinks, how long a
+// double click has, how far a press has to move before it is a drag, and
+// whether it wants animation at all.
+//
+// These were four constants in this codebase — `CARET_BLINK_MS` in nodes.js,
+// `DRAG_THRESHOLD` in dnd.js, and the 400ms/4px pair inside
+// `EventManager._clickDetail` — every one of them a guess at a number the
+// desktop already publishes and every other toolkit already reads.
+//
+// ## Why this is not part of the appearance ladder
+//
+// `appearance.js` climbs three sources for colour scheme and accent, because
+// those are answered by three different things and the portal is the modern
+// one. Nothing here has a portal equivalent: `org.freedesktop.appearance` has
+// four keys and none of them is a timing. XSETTINGS is the whole story, and
+// where there is no settings daemon — a bare `startx`, most window managers,
+// XQuartz — the defaults below stand.
+//
+// So this reads the map `xsettings.js` already maintains, rather than
+// standing up a source of its own.
+//
+// ## Two of these are read synchronously, which is what shapes the module
+//
+// A caret arms its blink inside `defaultFocus()` and a drag decides it has
+// started inside a mousemove. Neither has a round trip available, so
+// `desktopSettings(app)` is a synchronous read of an already-populated map
+// and `createRoot()` starts XSETTINGS **without awaiting it** — the settings
+// land in a few milliseconds and the first interaction is much later than
+// that. A field focused on the very first frame gets the defaults and the
+// desktop's cadence from the next focus onward; that is the one seam, and it
+// is worth more than the round trips on every app's startup path.
+
+import { beginXSettings, watchXSettings, xsettings } from './xsettings.js';
+
+/**
+ * What is true with no settings daemon to ask.
+ *
+ * These are **this renderer's existing constants**, not GTK's defaults. The
+ * two disagree — GTK blinks on a 1200ms cycle and drags at 8px, against 1060
+ * and 4 here — and changing what an app does on a desktop that never
+ * expressed a preference is a different decision from honouring one that
+ * did. This module only does the second.
+ */
+export const DEFAULTS = Object.freeze({
+  caretBlink: true,
+  // GTK, Qt and Windows all land within a few tens of milliseconds of this,
+  // and a blink out of step with the rest of the desktop is noticed even
+  // when the number cannot be named. Re-exported as `CARET_BLINK_MS` from
+  // `react-x11/node`, so an element drawing its own caret has one number to
+  // agree with rather than two.
+  caretBlinkMs: 530,
+  doubleClickMs: 400,
+  doubleClickDistance: 4,
+  // A press is a click until it moves this far. GTK's is 8; this is the
+  // DOM's, which is what the drag machinery here was built against.
+  dragThreshold: 4,
+  // Whether the desktop wants things to move. On by default because that is
+  // what the desktops that never say anything mean, and because the setting
+  // exists to be turned *off* — nobody enables animation, they disable it.
+  animations: true,
+  source: null,
+});
+
+const sessions = new WeakMap();
+
+/** A positive integer from the map, or undefined — a settings daemon can
+ *  export a key with a string value or a nonsense one, and a caret with a
+ *  blink period of `'fast'` would never come back on. */
+function positive(map, key) {
+  const value = map?.get(key);
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+/**
+ * An XSETTINGS map → the settings. Pure, and exported for the test: the
+ * in-process X server has no settings daemon, so this is the part of the
+ * path worth pinning without one.
+ *
+ * **`Net/CursorBlinkTime` is a full cycle**, on and off together — that is
+ * what GTK means by `gtk-cursor-blink-time` and what every daemon writes —
+ * and `caretBlinkMs` is how long the caret stays in *each* state, because
+ * that is the number that goes into a timer. Halving it is the whole
+ * conversion, and forgetting to is a caret that blinks at half speed and
+ * looks broken rather than wrong.
+ */
+export function fromXSettings(map) {
+  if (!map) return DEFAULTS;
+  const cycle = positive(map, 'Net/CursorBlinkTime');
+  const blink = map.get('Net/CursorBlink');
+  return Object.freeze({
+    // 0 is "do not blink at all", which is an accessibility setting rather
+    // than a preference: a moving thing on screen is what some people cannot
+    // read past. A caret that ignores it is the bug this module was written
+    // for. Only an explicit 0 turns it off — an absent key is not an answer.
+    caretBlink: blink !== 0,
+    caretBlinkMs: cycle
+      ? Math.max(1, Math.round(cycle / 2))
+      : DEFAULTS.caretBlinkMs,
+    doubleClickMs:
+      positive(map, 'Net/DoubleClickTime') ?? DEFAULTS.doubleClickMs,
+    doubleClickDistance:
+      positive(map, 'Net/DoubleClickDistance') ?? DEFAULTS.doubleClickDistance,
+    dragThreshold:
+      positive(map, 'Net/DndDragThreshold') ?? DEFAULTS.dragThreshold,
+    // `Gtk/EnableAnimations` is GTK's `gtk-enable-animations`, which every
+    // GNOME and Xfce session writes and which "reduce motion" in the
+    // accessibility panel turns off. Like the blink above, only an explicit
+    // 0 is an answer: a desktop that never exported the key has not asked
+    // for stillness, it has said nothing.
+    animations: map.get('Gtk/EnableAnimations') !== 0,
+    source: 'xsettings',
+  });
+}
+
+/**
+ * The settings for a connection, **synchronously**. Always a complete answer:
+ * the defaults before the daemon has been read, and on a display with none.
+ *
+ * Cached rather than derived per call, because `useDesktopSettings()` reads
+ * it through `useSyncExternalStore` and because the drag path calls it on
+ * every mousemove.
+ */
+export function desktopSettings(app) {
+  const session = sessions.get(app);
+  if (!session) return DEFAULTS;
+  if (!session.snapshot) {
+    session.snapshot = fromXSettings(xsettings(app));
+  }
+  return session.snapshot;
+}
+
+/**
+ * Start reading the settings on `app`.
+ *
+ * Deliberately **not** awaited by `createRoot()` — see the note at the top of
+ * the file. Never rejects.
+ */
+export function beginDesktopSettings(app) {
+  if (sessions.has(app)) return;
+  const session = { snapshot: null, listeners: new Set(), stop: null };
+  sessions.set(app, session);
+  beginXSettings(app).then(
+    () => {
+      if (!sessions.has(app)) return;
+      session.snapshot = null;
+      notify(session);
+      session.stop = watchXSettings(app, () => {
+        session.snapshot = null;
+        notify(session);
+      });
+    },
+    () => {
+      // no daemon, no raw connection, a headless mock: the defaults stand,
+      // which is what they are for
+    },
+  );
+}
+
+function notify(session) {
+  for (const fn of [...session.listeners]) {
+    try {
+      fn();
+    } catch {
+      // one subscriber throwing must not take the others with it
+    }
+  }
+}
+
+/** Subscribe to the settings changing. Not public — `useDesktopSettings()` is. */
+export function watchDesktopSettings(app, fn) {
+  let session = sessions.get(app);
+  if (!session) {
+    beginDesktopSettings(app);
+    session = sessions.get(app);
+  }
+  if (!session) return () => {};
+  session.listeners.add(fn);
+  return () => session.listeners.delete(fn);
+}
+
+/** Tear down with the root that started it. */
+export function endDesktopSettings(app) {
+  const session = sessions.get(app);
+  if (!session) return;
+  session.stop?.();
+  session.listeners.clear();
+  sessions.delete(app);
+}
+
+/**
+ * Test seam: state the settings without a settings daemon. Takes the same
+ * shape the hook returns; anything left out keeps its default.
+ */
+export function setDesktopSettingsForTests(app, values) {
+  let session = sessions.get(app);
+  if (!session) {
+    session = { snapshot: null, listeners: new Set(), stop: null };
+    sessions.set(app, session);
+  }
+  session.snapshot = Object.freeze({
+    ...DEFAULTS,
+    ...values,
+    source: values ? 'test' : null,
+  });
+  notify(session);
+  return session.snapshot;
+}