react-x11 1.2.0 → 2.0.0

package/src/compositing.js

@@ -0,0 +1,224 @@
+/**
+ * Is a compositing manager running?
+ *
+ * It matters because per-pixel transparency is not something the X server
+ * does. A depth-32 window's alpha channel is only meaningful to a compositor
+ * that blends it; with nothing composited, the server shows the raw pixels
+ * and a cleared corner is a *black* corner. So `<window transparent>` on a
+ * bare `startx`, a plain remote X server, or a session whose compositor was
+ * switched off looks worse than a square opaque window, not better.
+ *
+ * EWMH names the answer: the owner of the `_NET_WM_CM_Sn` selection, one per
+ * screen. Asking is one round trip, and it is asked once per connection
+ * during `createRoot`, which is already async — so by the time any window
+ * realizes, the answer is known synchronously and nothing has to block.
+ *
+ * The answer also changes while an app runs: compositors are started and
+ * stopped, and on some desktops that is a checkbox. XFixes reports it —
+ * `SelectSelectionInput` on the same selection — which is how this stays
+ * live rather than being a startup guess. That matters more than it sounds:
+ * a window's *visual* is fixed at CreateWindow and cannot follow, but
+ * whether the window paints its alpha channel or fills itself opaque is a
+ * paint-time decision, and paint-time decisions can change.
+ */
+
+import { requireExtension } from './extensions.js';
+
+const sessions = new WeakMap();
+
+/**
+ * What a connection currently knows. `supported` is null until the first
+ * probe answers — callers treat that as "no", because the fallback design is
+ * the one that works everywhere and a popup that flashes from square to
+ * rounded is better than one that flashes black.
+ */
+class CompositingSession {
+  constructor(app) {
+    this.app = app;
+    this.supported = null;
+    this.listeners = new Set();
+    this.stopped = false;
+    this._window = null;
+    this._selection = null;
+  }
+
+  _set(supported) {
+    const next = Boolean(supported);
+    if (this.supported === next) return;
+    this.supported = next;
+    for (const fn of [...this.listeners]) {
+      try {
+        fn(next);
+      } catch {
+        // a subscriber that throws must not take the others with it, nor
+        // the X event loop this runs on
+      }
+    }
+  }
+
+  subscribe(fn) {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  stop() {
+    this.stopped = true;
+    this.listeners.clear();
+  }
+}
+
+/** The atom name for a screen's compositing-manager selection. */
+const selectionName = (screen) => `_NET_WM_CM_S${screen}`;
+
+/**
+ * Start watching. Resolves once the first answer is in, so `createRoot` can
+ * await it and every window realized afterwards sees a settled value.
+ * Never rejects: a server without XFixes, or a mock with no X connection at
+ * all, simply reports "no compositor" and stops there.
+ */
+export async function beginCompositing(app, screen = 0) {
+  let session = sessions.get(app);
+  if (session) return session;
+  session = new CompositingSession(app);
+  sessions.set(app, session);
+
+  const X = app?.X;
+  if (!X || typeof X.GetSelectionOwner !== 'function') {
+    // headless mock, or an ntk too old to reach the raw connection
+    session._set(false);
+    return session;
+  }
+
+  try {
+    const atom = await internAtom(X, selectionName(screen));
+    session._selection = atom;
+    session._set(await selectionOwner(X, atom));
+    // Live updates are a bonus, not a requirement: without XFixes the
+    // startup answer simply stands for the life of the connection — which
+    // is also why the watch is not waited for. `supported` is settled by
+    // the line above, and nothing before the first realize reads the watch,
+    // so awaiting the XFixes probe here only lengthens the chain the first
+    // CreateWindow sits behind.
+    void watchSelection(app, session, atom).catch(() => {});
+  } catch {
+    if (session.supported === null) session._set(false);
+  }
+  return session;
+}
+
+function internAtom(X, name) {
+  return new Promise((resolve, reject) =>
+    X.InternAtom(false, name, (err, atom) =>
+      err ? reject(err) : resolve(atom),
+    ),
+  );
+}
+
+function selectionOwner(X, atom) {
+  return new Promise((resolve, reject) =>
+    X.GetSelectionOwner(atom, (err, owner) =>
+      // owner 0 is "nobody", which is exactly "no compositor"
+      err ? reject(err) : resolve(Boolean(owner)),
+    ),
+  );
+}
+
+/**
+ * XFixes selection notifications, delivered to a window we own. One event
+ * covers both directions: `owner` is the compositor's window when one takes
+ * over, and 0 when it goes away, whether it released the selection, closed
+ * the window or died.
+ */
+async function watchSelection(app, session, atom) {
+  const fixes = await requireExtension(app, 'fixes');
+  if (!fixes || session.stopped) return;
+  const X = app.X;
+  // A 1x1 InputOnly window off-screen, never mapped: XFixes addresses the
+  // notifications to a window, and this one exists only to be that address.
+  const id = X.AllocID();
+  X.CreateWindow(id, app.display.screen[0].root, -10, -10, 1, 1, 0, 0, 2, 0, {
+    eventMask: 0,
+  });
+  session._window = id;
+  const mask =
+    fixes.SelectionEventMask.SetSelectionOwner |
+    fixes.SelectionEventMask.SelectionWindowDestroy |
+    fixes.SelectionEventMask.SelectionClientClose;
+  X.on('event', (ev) => {
+    if (session.stopped) return;
+    // XFixes events carry a server-assigned type above the core range, so
+    // this cannot be confused with core SelectionNotify (31)
+    if (ev.type !== fixes.firstEvent) return;
+    if (ev.selection !== atom) return;
+    session._set(Boolean(ev.owner));
+  });
+  fixes.SelectSelectionInput(id, atom, mask);
+}
+
+/** Is a compositor running on this connection? False while unknown. */
+export function compositingActive(app) {
+  return sessions.get(app)?.supported === true;
+}
+
+/**
+ * Is transparency switched off for this process?
+ *
+ * `REACT_X11_NO_TRANSPARENCY=1` makes every display answer the way one with
+ * no 32-bit visual does: `transparent` is ignored, windows are created on
+ * the ordinary visual, and `'@supports transparency'` never matches. It is
+ * for looking at the fallback design on the machine you actually work on —
+ * the built-in menus and tooltips have two looks now, and the opaque one is
+ * otherwise reachable only by stopping the compositor for the whole session,
+ * which takes every other window on the desktop with it.
+ *
+ * `=== '1'` rather than a truthy test, like `REACT_X11_NO_PAINT_CACHE`: a
+ * stale `NO_TRANSPARENCY=0` left in a shell profile must not silently mean
+ * the opposite of what it says. Read per call rather than once at load, so
+ * a test can turn it on around one mount — and because the question it
+ * feeds is already one whose answer may change while an app runs.
+ */
+export function transparencyDisabled() {
+  return process.env.REACT_X11_NO_TRANSPARENCY === '1';
+}
+
+/**
+ * The 32-bit visual a transparent window would be created on, or null when
+ * this display has none — and null whatever it has when transparency is
+ * switched off. The one place that question is asked, so the switch cannot
+ * be half-applied: a window that took the visual but a `useSupports` that
+ * said no would size a tooltip for an arrow it then refused to draw.
+ */
+export function argbVisual(app) {
+  if (transparencyDisabled()) return null;
+  return app?.findArgbVisual?.() ?? null;
+}
+
+/** Subscribe to the answer changing. Returns an unsubscribe function. */
+export function watchCompositing(app, fn) {
+  const session = sessions.get(app);
+  if (!session) return () => {};
+  return session.subscribe(fn);
+}
+
+/** Tear down with the root that started it. */
+export function endCompositing(app) {
+  const session = sessions.get(app);
+  if (!session) return;
+  session.stop();
+  sessions.delete(app);
+}
+
+/**
+ * Test seam: force the answer without an X server, the way `setDebugPaint`
+ * and the animation clock are driven from tests. Also what the headless mock
+ * uses to model a display with or without a compositor.
+ */
+export function setCompositingForTests(app, supported) {
+  let session = sessions.get(app);
+  if (!session) {
+    session = new CompositingSession(app);
+    sessions.set(app, session);
+  }
+  session._set(supported);
+  return session;
+}

package/src/dbusmenu.js

@@ -0,0 +1,384 @@
+// `com.canonical.dbusmenu`, the exporter half.
+//
+// The protocol is a **stateful, id-addressed, revision-numbered tree**. React
+// hands us a fresh immutable array every render. Everything in this file is
+// the join between those two facts, and it is three problems that a C toolkit
+// holding a mutable `GtkMenuBar` simply does not have.
+//
+// **1. Ids must survive a re-render.** The shell caches properties against
+// integer ids, so an id that moved to a different row makes the panel draw
+// yesterday's label on today's item. `IdAllocator` keys on the path of
+// `key ?? label` segments — the same identity `MenuRow` already uses for its
+// React key — and never reuses a number within a process.
+//
+// **2. The diff picks the signal, and that choice is a performance decision.**
+// Plasma re-fetches a whole subtree on `LayoutUpdated` and only patches on
+// `ItemsPropertiesUpdated`. So a menu whose single `toggleState` flipped must
+// **not** bump the revision — which is exactly what a naive
+// `setState` → `LayoutUpdated(++rev, 0)` does on every keystroke, and it turns
+// one property write into a full re-walk of every menu in the app.
+//
+// **3. `AboutToShow` wants a synchronous boolean React cannot give.** See
+// `aboutToShow` below.
+//
+// Nothing here touches D-Bus. `snapshot()` and `diffSnapshots()` are pure, so
+// the parts that are easy to get wrong are testable with no bus, no X server
+// and no React — which is what `test/dbusmenu.test.js` does. The wire lives in
+// `globalmenu.js`.
+
+import {
+  hasSubmenu,
+  isSeparator,
+  isValidShortcut,
+  isVisible,
+} from './menuitem.js';
+
+export const DBUSMENU_IFACE = 'com.canonical.dbusmenu';
+
+/** The root of a dbusmenu tree is always id 0, and is never an item. */
+export const ROOT_ID = 0;
+
+/**
+ * The D-Bus type of every item property we emit.
+ *
+ * A table rather than inline variants because two places need to agree on it:
+ * the layout serialiser and `ItemsPropertiesUpdated`. It is also the list of
+ * properties `GetLayout(…, propertyNames)` can filter on, so a shell asking
+ * for `['label']` gets exactly the labels.
+ */
+export const PROPERTY_TYPES = {
+  type: 's',
+  label: 's',
+  enabled: 'b',
+  visible: 'b',
+  'icon-name': 's',
+  'icon-data': 'ay',
+  shortcut: 'aas',
+  'toggle-type': 's',
+  'toggle-state': 'i',
+  'children-display': 's',
+  disposition: 's',
+};
+
+// dbusmenu defines a default for these, and the spec is explicit that a
+// property at its default **should not be sent**. It is not only traffic: a
+// shell diffing properties it was told about will happily store `enabled:true`
+// on ten thousand items that never said anything of the sort.
+const DEFAULTS = {
+  type: 'standard',
+  enabled: true,
+  visible: true,
+  'toggle-state': 0,
+  disposition: 'normal',
+};
+
+/**
+ * The dbusmenu properties for one item, defaults omitted.
+ *
+ * `icon` is deliberately absent: it is a react-x11 drawing callback, and the
+ * desktop cannot call a function. An item that wants an icon in *both* menus
+ * carries `icon` for ours and `iconName`/`iconData` for the panel's.
+ */
+export function itemProperties(item) {
+  const props = {};
+  const set = (name, value) => {
+    if (value === undefined || value === null) return;
+    if (DEFAULTS[name] === value) return;
+    props[name] = value;
+  };
+
+  if (isSeparator(item)) {
+    // A separator has nothing else to say, and a label on one is a shell bug
+    // waiting to happen — some panels draw it.
+    set('type', 'separator');
+    set('visible', isVisible(item));
+    return props;
+  }
+
+  set('label', item.label);
+  set('enabled', item.enabled);
+  set('visible', item.visible);
+  set('icon-name', item.iconName);
+  set('icon-data', item.iconData);
+  set('toggle-type', item.toggleType);
+  set('toggle-state', item.toggleState);
+  set('disposition', item.disposition);
+  // Only ever a claim about children that exist. A parent that promises a
+  // submenu and then answers `GetLayout` with none leaves an arrow pointing
+  // at an empty popup.
+  if (hasSubmenu(item)) props['children-display'] = 'submenu';
+  // A malformed shortcut is dropped rather than sent. dbus-native would throw
+  // from inside the marshaller — that is mid-reply, on the bus thread, where
+  // the only symptom is a panel with no menu at all. `checkShortcut` is what
+  // tells the developer, in development, at the item that is wrong.
+  if (isValidShortcut(item.shortcut)) props.shortcut = item.shortcut;
+
+  return props;
+}
+
+// --------------------------------------------------------------------------
+// Stable ids
+// --------------------------------------------------------------------------
+
+/**
+ * Integer ids that survive re-renders.
+ *
+ * An item is identified by its `key ?? label` within its parent — the same
+ * identity `MenuRow` keys its React element on, so an app that already gave
+ * its items stable keys gets stable ids for free and one that did not gets
+ * exactly the same answer both places.
+ *
+ * Three rules that are not obvious:
+ *
+ * - **Ids are never reused.** A menu that loses an item and later grows a
+ *   different one at the same path must not hand the shell an id it already
+ *   has properties cached against. So the counter only ever goes up, and a
+ *   forgotten path is forgotten for good.
+ * - **Separators are keyed among separators**, not by their index in the
+ *   list. Keying them by list position renumbers every separator below an
+ *   inserted item, which turns a one-row insertion into a structural change
+ *   across the whole menu.
+ * - **Identity is scoped to the parent's id, not to a joined string path.**
+ *   See `idFor`.
+ */
+export class IdAllocator {
+  constructor() {
+    this.ids = new Map();
+    this.next = ROOT_ID + 1;
+  }
+
+  /**
+   * The id for `segment` under `parentId`, allocated on first sight.
+   *
+   * Keyed against the parent's **id** rather than against a joined string
+   * path, because labels are arbitrary text and any character chosen to join
+   * a path is one a label can contain — with `/`, an item called `a/b` under
+   * `p` collides with `b` under `p/a`. A parent's id is already a unique
+   * integer, so there is nothing to escape.
+   */
+  idFor(parentId, segment) {
+    const key = `${parentId}\u0000${segment}`;
+    let id = this.ids.get(key);
+    if (id === undefined) {
+      id = this.next++;
+      this.ids.set(key, id);
+    }
+    return id;
+  }
+}
+
+/**
+ * Sibling path segments, each unique within its list.
+ *
+ * The delimiter is a NUL, written as a `\u0000` **escape** rather than as
+ * a literal byte: a NUL in the source makes git treat the file as binary
+ * — no diff, no blame, no three-way merge, on the file holding the
+ * trickiest logic in the feature — and any tool that normalises it would
+ * silently change the disambiguator.
+ *
+ * The occurrence count goes on **every** segment rather than only on the
+ * duplicates, which is what makes a collision impossible rather than merely
+ * unlikely. Appending only to the duplicates looks equivalent and is not:
+ * three siblings labelled `A`, `A` and `A 1` produce `A`, `A 1`, `A 1`, so
+ * the last two share an id — one row overwrites the other and the panel is
+ * handed a tree with the same id in it twice. With the count always present
+ * the delimiter splits base from count unambiguously, and two distinct items
+ * cannot agree.
+ */
+function segmentsFor(items) {
+  const seen = new Map();
+  let separators = 0;
+  return items.map((item, index) => {
+    const base = isSeparator(item)
+      ? `\u0000sep${separators++}`
+      : String(item.key ?? item.label ?? `\u0000at${index}`);
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    return `${base}\u0000${n}`;
+  });
+}
+
+// --------------------------------------------------------------------------
+// Snapshots
+// --------------------------------------------------------------------------
+
+/**
+ * The whole menu as `Map<id, { id, parent, props, childIds, item }>`, which is
+ * both what the D-Bus methods answer from and what the next render is diffed
+ * against.
+ *
+ * `menus` is `MenuBar`'s own prop — `[{ label, items }]` — so a bar menu is
+ * just an item with children, which is exactly what dbusmenu's root is.
+ */
+export function snapshot(menus, alloc) {
+  const nodes = new Map();
+
+  const walk = (items, parentId) => {
+    const segments = segmentsFor(items);
+    const childIds = [];
+    items.forEach((item, index) => {
+      const id = alloc.idFor(parentId, segments[index]);
+      childIds.push(id);
+      nodes.set(id, {
+        id,
+        parent: parentId,
+        props: itemProperties(item),
+        childIds: walk(item.items ?? [], id),
+        item,
+      });
+    });
+    return childIds;
+  };
+
+  nodes.set(ROOT_ID, {
+    id: ROOT_ID,
+    parent: null,
+    props: { 'children-display': 'submenu' },
+    childIds: walk(menus ?? [], ROOT_ID),
+    item: null,
+  });
+  return nodes;
+}
+
+const sameIds = (a, b) =>
+  a.length === b.length && a.every((v, i) => v === b[i]);
+
+/** Property equality, deep enough for the values dbusmenu carries. */
+function sameValue(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => sameValue(v, b[i]));
+  }
+  // Buffers, for icon-data
+  if (ArrayBuffer.isView(a) && ArrayBuffer.isView(b)) {
+    return Buffer.from(a.buffer, a.byteOffset, a.byteLength).equals(
+      Buffer.from(b.buffer, b.byteOffset, b.byteLength),
+    );
+  }
+  return false;
+}
+
+/** The lowest node that has every one of `ids` beneath it (or at it). */
+function nearestCommonAncestor(nodes, ids) {
+  if (ids.length === 0) return ROOT_ID;
+  const chainOf = (id) => {
+    const out = [];
+    for (let cur = id; cur != null; cur = nodes.get(cur)?.parent)
+      out.unshift(cur);
+    return out;
+  };
+  let common = chainOf(ids[0]);
+  for (const id of ids.slice(1)) {
+    const chain = chainOf(id);
+    let i = 0;
+    while (i < common.length && i < chain.length && common[i] === chain[i]) i++;
+    common = common.slice(0, i);
+    if (common.length === 0) break;
+  }
+  return common.length ? common[common.length - 1] : ROOT_ID;
+}
+
+/**
+ * What to tell the shell about the step from `prev` to `next`.
+ *
+ * ```
+ * { kind: 'none' }
+ * { kind: 'properties', updated: [[id, props]], removed: [[id, names]] }
+ * { kind: 'layout', parent: id }
+ * ```
+ *
+ * **The whole point is that `'properties'` does not bump the revision.**
+ * Structure — an item appearing, disappearing or moving — is the only thing
+ * that invalidates a cached layout; a label, a check mark or an `enabled`
+ * flag is a patch, and sending `LayoutUpdated` for one costs a full re-walk
+ * of the subtree in every shell that implements the protocol properly.
+ *
+ * `parent` is the nearest common ancestor of the subtrees that actually
+ * changed, so a change inside one menu does not invalidate the other five.
+ * `0` is the spec's "the whole layout is invalid" and stays available as the
+ * honest answer when changes are scattered.
+ */
+export function diffSnapshots(prev, next) {
+  if (!prev) return { kind: 'layout', parent: ROOT_ID };
+
+  const structural = [];
+  for (const [id, node] of next) {
+    const before = prev.get(id);
+    if (!before) continue; // its parent's childIds changed; that is the signal
+    if (!sameIds(before.childIds, node.childIds)) structural.push(id);
+  }
+  // A node that vanished entirely and whose parent also vanished is covered by
+  // the surviving ancestor above. One whose parent survived is covered by that
+  // parent's childIds. So `structural` is empty only if the shape is identical.
+  if (structural.length > 0) {
+    return { kind: 'layout', parent: nearestCommonAncestor(next, structural) };
+  }
+
+  const updated = [];
+  const removed = [];
+  for (const [id, node] of next) {
+    const before = prev.get(id);
+    if (!before) continue;
+    const changed = {};
+    const gone = [];
+    for (const [name, value] of Object.entries(node.props)) {
+      if (!sameValue(before.props[name], value)) changed[name] = value;
+    }
+    for (const name of Object.keys(before.props)) {
+      if (!(name in node.props)) gone.push(name);
+    }
+    if (Object.keys(changed).length > 0) updated.push([id, changed]);
+    if (gone.length > 0) removed.push([id, gone]);
+  }
+
+  if (updated.length === 0 && removed.length === 0) return { kind: 'none' };
+  return { kind: 'properties', updated, removed };
+}
+
+// --------------------------------------------------------------------------
+// Answering the protocol
+// --------------------------------------------------------------------------
+
+/** `props` filtered to `names`, or all of them when the shell asked for none. */
+function filterProps(props, names) {
+  if (!names || names.length === 0) return props;
+  const out = {};
+  // `hasOwn`, not `in`: a shell asking for `constructor` or `toString` would
+  // otherwise be answered with a function, which fails to marshal and turns
+  // one nonsense property name into an error reply for the whole call.
+  for (const name of names)
+    if (Object.hasOwn(props, name)) out[name] = props[name];
+  return out;
+}
+
+/**
+ * `GetLayout`'s recursive `(ia{sv}av)`, as plain values — the caller wraps
+ * them for the wire.
+ *
+ * `depth` follows the spec: `-1` recurses all the way, `0` stops at this item,
+ * `n` takes n levels of children.
+ */
+export function layoutOf(nodes, id, depth, names) {
+  const node = nodes.get(id);
+  if (!node) return null;
+  const children =
+    depth === 0
+      ? []
+      : node.childIds
+          .map((child) =>
+            layoutOf(nodes, child, depth < 0 ? -1 : depth - 1, names),
+          )
+          .filter(Boolean);
+  return [node.id, filterProps(node.props, names), children];
+}
+
+/** `GetGroupProperties`' `a(ia{sv})`. Unknown ids are skipped, not an error. */
+export function groupProperties(nodes, ids, names) {
+  const wanted = ids && ids.length > 0 ? ids : [...nodes.keys()];
+  const out = [];
+  for (const id of wanted) {
+    const node = nodes.get(id);
+    if (node) out.push([id, filterProps(node.props, names)]);
+  }
+  return out;
+}

package/src/debug.d.ts

@@ -0,0 +1,63 @@
+// Hand-written declarations for `react-x11/debug` (docs/debugging.md).
+
+export type TraceSink = 'summary' | 'requests' | 'chrome';
+
+export interface TraceStats {
+  /** Requests sent since the trace attached. */
+  requests: number;
+  bytesOut: number;
+  /** Replies received (each one is a round trip the client waited for). */
+  replies: number;
+  events: number;
+  errors: number;
+  bytesIn: number;
+  /** Decoded request name — e.g. 'CopyArea', 'Render.CompositeGlyphs32' —
+   * to how many times it was sent. */
+  byOpcode: Map<string, number>;
+  /** ntk's rounded-rect fast path (ntk >= 6.7.0): boxes emitted as cached
+   * corner glyphs + FillRectangles, against those that fell back to
+   * polygon rasterization, counted by reason. Both zero on older ntk. */
+  shapes: ShapeStats;
+}
+
+export interface ShapeStats {
+  /** Rounded boxes drawn as corner glyphs + rects. */
+  hits: number;
+  /** Bail-out reason — 'fractional', 'gradient', 'clip-mask', 'dashes',
+   * 'transform', 'radius-cap', 'composite-op', 'geometry', 'radii-mix',
+   * 'join' — to how many draws took it. */
+  misses: Record<string, number>;
+}
+
+export interface TraceOptions {
+  /** Trace one specific ntk App. Without it, the trace follows every
+   * connection the renderer has open or opens later. */
+  app?: unknown;
+  /** 'summary' (default): totals at stop. 'requests': a stderr line per
+   * request and per frame. 'chrome': Trace Event JSON written to `path`. */
+  sink?: TraceSink;
+  /** Output file for the 'chrome' sink. Default 'react-x11-trace.json'. */
+  path?: string;
+  /** Capture a JS stack per request (node-x11's seq2stack), so an async X
+   * error names the call that sent it. One Error capture per request. */
+  seq2stack?: boolean;
+}
+
+export interface TraceSession {
+  /** Live totals; the same object `stop()` returns. */
+  stats: TraceStats;
+  /** Detach from every connection, flush the sink, return the totals. */
+  stop(): TraceStats;
+}
+
+export function startTrace(options?: TraceOptions): TraceSession;
+
+/** What `REACT_X11_TRACE=<spec>` calls at startup. Grammar:
+ * `summary` | `requests[+stacks]` | `chrome[+stacks]:<path>`. */
+export function startEnvTrace(spec: string): TraceSession | null;
+
+/** The one-line rounded-box tally the 'summary' sink prints, or null when
+ * nothing drew a rounded box. */
+export function formatShapes(
+  shapes: ShapeStats | null | undefined,
+): string | null;