react-cheminfo 0.8.0 → 0.10.0

package/src/scatter/core/lassoPath.ts

@@ -0,0 +1,127 @@
+const DEFAULT_CAPACITY = 256;
+
+/**
+ * The outline a pointer has drawn, as a buffer that is only partly in use.
+ *
+ * The two arrays are grown by doubling and never shrunk, and `length` says how
+ * much of them is the path. A drag emits a pointer move every frame or more
+ * often; growing the buffer on each one would put a fresh pair of typed arrays
+ * in front of the collector sixty times a second, during the one interaction
+ * where a dropped frame is visible as a kink in the line the user is drawing.
+ */
+export interface LassoPath {
+  /** Horizontal position of each vertex; only the first `length` are in use. */
+  xs: Float64Array;
+  /** Vertical position of each vertex; only the first `length` are in use. */
+  ys: Float64Array;
+  /** How many vertices have been kept. */
+  length: number;
+}
+
+/**
+ * An empty path, with room to grow.
+ * @param capacity - How many vertices to make room for before the first growth; at least one, and rounded down. Defaults to 256, which is a couple of seconds of dragging.
+ * @returns The path, holding no vertex yet.
+ */
+export function createLassoPath(capacity = DEFAULT_CAPACITY): LassoPath {
+  const size = Number.isFinite(capacity)
+    ? Math.max(1, Math.floor(capacity))
+    : DEFAULT_CAPACITY;
+  return { xs: new Float64Array(size), ys: new Float64Array(size), length: 0 };
+}
+
+/**
+ * Empty a path without giving up the room it has claimed.
+ *
+ * The buffers are kept, so the second lasso of a session and the fiftieth cost
+ * nothing to start. Whatever is left past `length` is never read.
+ * @param path - The path to empty.
+ */
+export function resetLassoPath(path: LassoPath): void {
+  path.length = 0;
+}
+
+/**
+ * Add a vertex, unless it is too near the last one kept.
+ *
+ * The distance is measured from the last vertex that was kept, not from the
+ * last position the pointer reported, so consecutive vertices are always at
+ * least `minDistance` apart however slowly the pointer is moving. Measuring
+ * from the raw sample instead would let a slow drag across the whole plot keep
+ * a single vertex, and the outline would close as a straight line between
+ * where the drag started and where it ended.
+ * @param path - The path to add to; its buffers are doubled when full.
+ * @param x - Horizontal position of the vertex, in pixels.
+ * @param y - Vertical position of the vertex, in pixels.
+ * @param minDistance - How far the pointer has to have moved for the vertex to be worth keeping, in pixels. Nothing is dropped when it is zero, negative, or not finite.
+ * @returns Whether the vertex was kept. A position that is not finite never is.
+ */
+export function appendLassoPoint(
+  path: LassoPath,
+  x: number,
+  y: number,
+  minDistance: number,
+): boolean {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+
+  if (path.length > 0) {
+    const lastX = path.xs[path.length - 1];
+    const lastY = path.ys[path.length - 1];
+    if (lastX !== undefined && lastY !== undefined) {
+      const gate =
+        Number.isFinite(minDistance) && minDistance > 0
+          ? minDistance * minDistance
+          : 0;
+      const deltaX = x - lastX;
+      const deltaY = y - lastY;
+      if (deltaX * deltaX + deltaY * deltaY < gate) return false;
+    }
+  }
+
+  if (path.length >= path.xs.length || path.length >= path.ys.length) {
+    growLassoPath(path);
+  }
+  path.xs[path.length] = x;
+  path.ys[path.length] = y;
+  path.length += 1;
+  return true;
+}
+
+/**
+ * The path as an SVG `d` attribute.
+ *
+ * Coordinates are rounded to a tenth of a pixel. A lasso is drawn at a
+ * resolution the eye cannot resolve past that, and the full doubles would put
+ * seventeen characters per vertex into an attribute that is rewritten on every
+ * frame of the drag.
+ * @param path - The path to write out.
+ * @param close - Whether to close the ring with a `Z`, which is what turns the drawn line into the shape that is about to be tested.
+ * @returns The `d` attribute, or an empty string when the path holds no vertex.
+ */
+export function lassoPathData(path: LassoPath, close: boolean): string {
+  const count = Math.min(path.length, path.xs.length, path.ys.length);
+  let data = '';
+  for (let index = 0; index < count; index++) {
+    const x = path.xs[index];
+    const y = path.ys[index];
+    if (x === undefined || y === undefined) break;
+    data += `${index === 0 ? 'M' : ' L'}${roundToTenth(x)},${roundToTenth(y)}`;
+  }
+  if (data.length === 0) return '';
+  return close ? `${data}Z` : data;
+}
+
+function growLassoPath(path: LassoPath): void {
+  const capacity = Math.max(1, Math.min(path.xs.length, path.ys.length)) * 2;
+  const xs = new Float64Array(capacity);
+  const ys = new Float64Array(capacity);
+  xs.set(path.xs);
+  ys.set(path.ys);
+  path.xs = xs;
+  path.ys = ys;
+}
+
+function roundToTenth(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(value * 10) / 10;
+}

package/src/scatter/core/polygon.ts

@@ -0,0 +1,155 @@
+import type { PixelBounds, ScreenPoints } from './screenPoints.ts';
+
+/**
+ * Whether a point falls inside a polygon.
+ *
+ * A ray cast from the point towards growing x, counting the edges it crosses:
+ * an odd count is inside, an even one is outside. Both tests that decide a
+ * crossing are half-open, and that is what settles the boundary. An edge is
+ * only considered for the ys it spans from its lower end up to, but not
+ * including, its upper end; and the crossing has to sit strictly beyond the
+ * point. So on the square `(0,0) (10,0) (10,10) (0,10)` the two edges meeting
+ * at `(0,0)` count as inside — `(5,0)` and `(0,5)` are in — while the two
+ * meeting at `(10,10)` count as outside, and `(5,10)` and `(10,5)` are out. Of
+ * the four corners only `(0,0)` is inside; `(10,0)`, `(0,10)` and `(10,10)`
+ * are not.
+ *
+ * The asymmetry is the point of the convention rather than an accident of it:
+ * it is what stops two polygons sharing an edge from both claiming the samples
+ * that lie along it, and what keeps a point from toggling in and out as a
+ * lasso is dragged a hundredth of a pixel.
+ * @param x - Horizontal position of the point, in pixels.
+ * @param y - Vertical position of the point, in pixels.
+ * @param xs - Horizontal position of each vertex, in order around the ring; the ring is closed for you.
+ * @param ys - Vertical position of each vertex, in the same order.
+ * @param vertexCount - How many leading entries of the two arrays are vertices, so that a growing buffer can be passed whole. Their common length when omitted.
+ * @returns Whether the point is inside; always `false` for fewer than three vertices, since nothing thinner than a triangle holds anything.
+ */
+export function pointInPolygon(
+  x: number,
+  y: number,
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount?: number,
+): boolean {
+  const count = usableVertexCount(xs, ys, vertexCount);
+  if (count < 3) return false;
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+
+  let previousX = xs[count - 1];
+  let previousY = ys[count - 1];
+  if (previousX === undefined || previousY === undefined) return false;
+
+  let inside = false;
+  for (let index = 0; index < count; index++) {
+    const currentX = xs[index];
+    const currentY = ys[index];
+    if (currentX === undefined || currentY === undefined) break;
+    if (currentY > y !== previousY > y) {
+      const crossing =
+        ((previousX - currentX) * (y - currentY)) / (previousY - currentY) +
+        currentX;
+      if (x < crossing) inside = !inside;
+    }
+    previousX = currentX;
+    previousY = currentY;
+  }
+  return inside;
+}
+
+/**
+ * The rectangle a polygon's vertices span.
+ * @param xs - Horizontal position of each vertex.
+ * @param ys - Vertical position of each vertex.
+ * @param vertexCount - How many leading entries are vertices. Their common length when omitted.
+ * @returns The rectangle, or `null` when no vertex has two finite coordinates. Vertices that do not are left out rather than poisoning the bounds with a `NaN`.
+ */
+export function polygonBounds(
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount?: number,
+): PixelBounds | null {
+  const count = usableVertexCount(xs, ys, vertexCount);
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  let bounded = false;
+  for (let index = 0; index < count; index++) {
+    const vertexX = xs[index];
+    const vertexY = ys[index];
+    if (vertexX === undefined || vertexY === undefined) break;
+    if (!Number.isFinite(vertexX) || !Number.isFinite(vertexY)) continue;
+    if (vertexX < minX) minX = vertexX;
+    if (vertexX > maxX) maxX = vertexX;
+    if (vertexY < minY) minY = vertexY;
+    if (vertexY > maxY) maxY = vertexY;
+    bounded = true;
+  }
+  return bounded ? { minX, minY, maxX, maxY } : null;
+}
+
+/**
+ * Which of many points fall inside a polygon.
+ *
+ * Each point is measured against the polygon's rectangle first, which is four
+ * comparisons and rejects nearly every point of a cloud that a lasso has
+ * enclosed a corner of; only the survivors pay for a walk over every edge. The
+ * saving is the whole reason the prefilter is here: a released lasso has a
+ * vertex for every few pixels the pointer travelled, so the unfiltered cost is
+ * the point count times a few hundred, per drag, on the frame the user is
+ * waiting for.
+ *
+ * Nothing is allocated per point. The rectangle is computed once, the answer
+ * is written into the mask, and the mask itself is reused when the caller
+ * hands one of the right size back.
+ * @param points - Where every point sits on screen.
+ * @param xs - Horizontal position of each vertex.
+ * @param ys - Vertical position of each vertex.
+ * @param vertexCount - How many leading entries are vertices. Their common length when omitted.
+ * @param into - A mask to write into, so a drag does not allocate one per frame. It is used only when it already has one entry per point; otherwise a new one is allocated, because silently answering about a different number of points is worse than the allocation.
+ * @returns One entry per point, `1` for inside and `0` for outside. All zeros for fewer than three vertices.
+ */
+export function pointsInPolygon(
+  points: ScreenPoints,
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount?: number,
+  into?: Uint8Array,
+): Uint8Array {
+  const pointsX = points.x;
+  const pointsY = points.y;
+  const total = Math.min(pointsX.length, pointsY.length);
+  const mask = into?.length === total ? into : new Uint8Array(total);
+
+  const count = usableVertexCount(xs, ys, vertexCount);
+  const bounds = count < 3 ? null : polygonBounds(xs, ys, count);
+  if (bounds === null) {
+    mask.fill(0);
+    return mask;
+  }
+
+  const { minX, minY, maxX, maxY } = bounds;
+  for (let index = 0; index < total; index++) {
+    const pointX = pointsX[index];
+    const pointY = pointsY[index];
+    if (pointX === undefined || pointY === undefined) break;
+    if (pointX < minX || pointX > maxX || pointY < minY || pointY > maxY) {
+      mask[index] = 0;
+      continue;
+    }
+    mask[index] = pointInPolygon(pointX, pointY, xs, ys, count) ? 1 : 0;
+  }
+  return mask;
+}
+
+function usableVertexCount(
+  xs: Float64Array,
+  ys: Float64Array,
+  vertexCount: number | undefined,
+): number {
+  const available = Math.min(xs.length, ys.length);
+  if (vertexCount === undefined) return available;
+  if (!Number.isFinite(vertexCount)) return 0;
+  return Math.max(0, Math.min(available, Math.floor(vertexCount)));
+}

package/src/scatter/core/scatterSelection.ts

@@ -0,0 +1,88 @@
+/** How a fresh set of hits joins the selection that is already on screen. */
+export type ScatterSelectionMode = 'replace' | 'add' | 'remove';
+
+/**
+ * The selection a gesture leaves behind, from the one before it and its hits.
+ *
+ * The result is always as long as `base`, because that is the cloud's own
+ * length and the only length a selection is meaningful at. A `hits` mask that
+ * is short leaves the points past its end untouched — an honest reading of "no
+ * hit there" — rather than throwing at the end of a drag.
+ *
+ * Every entry written is `0` or `1`, so a mask that has been through this
+ * function can be compared with `toStrictEqual` and handed to a renderer that
+ * only checks for truthiness, whatever the caller filled its input with.
+ * @param base - The selection before the gesture, one entry per point.
+ * @param hits - The points the gesture caught, one entry per point; a non-zero entry is a hit.
+ * @param mode - Whether the hits stand alone, join the selection, or leave it.
+ * @param into - A mask to write into, so a drag does not allocate one per frame. It is used only when it already has one entry per point; otherwise a new one is allocated.
+ * @returns The new selection, one `0` or `1` per point.
+ */
+export function mergeScatterSelection(
+  base: Uint8Array,
+  hits: Uint8Array,
+  mode: ScatterSelectionMode,
+  into?: Uint8Array,
+): Uint8Array {
+  const total = base.length;
+  const merged = into?.length === total ? into : new Uint8Array(total);
+
+  const replacing = mode === 'replace';
+  const removing = mode === 'remove';
+  for (let index = 0; index < total; index++) {
+    const previous = base[index];
+    const hit = hits[index];
+    const wasSelected = previous !== undefined && previous !== 0;
+    const isHit = hit !== undefined && hit !== 0;
+    let selected: boolean;
+    if (replacing) selected = isHit;
+    else if (removing) selected = wasSelected && !isHit;
+    else selected = wasSelected || isHit;
+    merged[index] = selected ? 1 : 0;
+  }
+  return merged;
+}
+
+/**
+ * Which points a mask has selected, as their indices.
+ *
+ * The list is what a caller reports, serialises or hands to a table, so it is
+ * a plain array of numbers and not a third mask; it comes out ascending
+ * because the mask is read in order.
+ * @param mask - One entry per point; a non-zero entry is selected.
+ * @returns The selected indices, ascending.
+ */
+export function scatterSelectedIndices(mask: Uint8Array): number[] {
+  const indices: number[] = [];
+  for (let index = 0; index < mask.length; index++) {
+    const flag = mask[index];
+    if (flag !== undefined && flag !== 0) indices.push(index);
+  }
+  return indices;
+}
+
+/**
+ * A mask over a cloud, from the indices that are selected.
+ *
+ * The inverse of {@link scatterSelectedIndices}, and the door a selection
+ * restored from a URL or a parent component comes in through. An index that is
+ * negative, past the end, or not a whole number is dropped rather than
+ * throwing: those lists arrive from outside, and a stale index in one is a
+ * reason to select one point fewer, not to fail a render.
+ * @param indices - The selected indices, in any order and possibly repeated.
+ * @param count - How many points the cloud holds.
+ * @returns One `0` or `1` per point.
+ */
+export function scatterSelectionMask(
+  indices: Iterable<number>,
+  count: number,
+): Uint8Array {
+  const total = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+  const mask = new Uint8Array(total);
+  for (const index of indices) {
+    if (!Number.isInteger(index)) continue;
+    if (index < 0 || index >= total) continue;
+    mask[index] = 1;
+  }
+  return mask;
+}

package/src/scatter/core/screenPoints.ts

@@ -0,0 +1,110 @@
+/**
+ * Where every point sits on screen, as two parallel arrays.
+ *
+ * Parallel typed arrays rather than an array of objects: the hit tests are the
+ * only code that reads them, they read them in index order, and an `{ x, y }`
+ * per point would allocate one object per sample on every relayout.
+ */
+export interface ScreenPoints {
+  /** Horizontal position of each point, in pixels from the plot's left. */
+  x: Float64Array;
+  /** Vertical position of each point, in pixels from the plot's top. */
+  y: Float64Array;
+}
+
+/** The rectangle a set of coordinates spans, in pixels. */
+export interface PixelBounds {
+  /** Smallest horizontal position. */
+  minX: number;
+  /** Smallest vertical position. */
+  minY: number;
+  /** Largest horizontal position. */
+  maxX: number;
+  /** Largest vertical position. */
+  maxY: number;
+}
+
+/**
+ * The point nearest a position, when one is close enough to have been aimed at.
+ *
+ * Distances are compared squared. The caller only ever ranks them, so the
+ * square root would be computed once per point on every pointer move and then
+ * thrown away; a hover test over twenty thousand points is exactly where that
+ * is not affordable.
+ *
+ * A tie goes to the lower index. Two points that land on the same pixel then
+ * resolve the same way twice running, instead of the readout flickering
+ * between them as the pointer jitters.
+ * @param points - Where every point sits on screen.
+ * @param x - Horizontal position to search from, in pixels from the plot's left.
+ * @param y - Vertical position to search from, in pixels from the plot's top.
+ * @param radius - How far from that position to look, in pixels; a point exactly that far away still counts.
+ * @param included - One entry per point, a zero meaning the point cannot be hit. Every point can be hit when it is omitted, and a point past the end of a shorter mask cannot.
+ * @returns The index of the nearest point within the radius, or `-1` when no point is within it.
+ */
+export function nearestPointIndex(
+  points: ScreenPoints,
+  x: number,
+  y: number,
+  radius: number,
+  included?: Uint8Array,
+): number {
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(radius)) {
+    return -1;
+  }
+  const xs = points.x;
+  const ys = points.y;
+  let count = Math.min(xs.length, ys.length);
+  if (included !== undefined) count = Math.min(count, included.length);
+
+  const limit = radius * radius;
+  let nearest = -1;
+  let nearestDistance = 0;
+  for (let index = 0; index < count; index++) {
+    if (included?.[index] === 0) continue;
+    const pointX = xs[index];
+    const pointY = ys[index];
+    if (pointX === undefined || pointY === undefined) break;
+    const deltaX = pointX - x;
+    const deltaY = pointY - y;
+    const distance = deltaX * deltaX + deltaY * deltaY;
+    if (distance > limit) continue;
+    if (nearest === -1 || distance < nearestDistance) {
+      nearest = index;
+      nearestDistance = distance;
+    }
+  }
+  return nearest;
+}
+
+/**
+ * Which points fall inside a rectangle.
+ *
+ * A zoomed plot draws only part of its cloud, and the dots left outside the
+ * frame are clipped rather than dropped: they are still in the coordinate
+ * arrays, still one pixel away from the frame's edge, and still the nearest
+ * point to a pointer resting just inside it. Without this mask a reader
+ * zoomed in on one crowd gets hover cards about samples they cannot see.
+ * @param points - Where every point sits on screen.
+ * @param bounds - The rectangle, normally the plot's own; a point on an edge is inside it.
+ * @param into - A mask to write into, so a resize does not allocate one per frame. It is used only when it already has one entry per point.
+ * @returns One entry per point, `1` for inside.
+ */
+export function pointsWithinBounds(
+  points: ScreenPoints,
+  bounds: PixelBounds,
+  into?: Uint8Array,
+): Uint8Array {
+  const xs = points.x;
+  const ys = points.y;
+  const count = Math.min(xs.length, ys.length);
+  const mask = into?.length === count ? into.fill(0) : new Uint8Array(count);
+  const { minX, minY, maxX, maxY } = bounds;
+  for (let index = 0; index < count; index++) {
+    const x = xs[index] ?? Number.NaN;
+    const y = ys[index] ?? Number.NaN;
+    if (x < minX || x > maxX || y < minY || y > maxY) continue;
+    mask[index] = 1;
+  }
+  return mask;
+}

package/src/scatter/ui/ScatterEllipseLayer.tsx

@@ -0,0 +1,153 @@
+import type { ReactElement } from 'react';
+import { memo, useEffect, useRef } from 'react';
+
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import type { EllipsePoint, EllipseSize } from '../core/confidenceEllipse.ts';
+import { confidenceEllipse } from '../core/confidenceEllipse.ts';
+
+import { scatterOutlineShape } from './scatterOutlineShape.tsx';
+
+/** What {@link ScatterEllipseLayer} needs. */
+export interface ScatterEllipseLayerProps {
+  /** Horizontal coordinate of every point, in data units. */
+  x: ArrayLike<number>;
+  /** Vertical coordinate of every point, in the same order. */
+  y: ArrayLike<number>;
+  /**
+   * Which group each point belongs to, as an index into `colors`. A point with
+   * `-1`, or an index outside the range, is left out of every outline.
+   */
+  groupOf: ArrayLike<number>;
+  /** The colour of each group, in group order. */
+  colors: readonly string[];
+  /** Data to pixels, horizontally. */
+  scaleX: ChartScale;
+  /** Data to pixels, vertically; its `factor` is negative. */
+  scaleY: ChartScale;
+  /**
+   * How much of each group its outline holds.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many points a group needs before it is outlined at all. Below it the
+   * shape says more about the sample than about the group.
+   * @default 3
+   */
+  minimumPoints?: number;
+  /**
+   * How strongly each outline is drawn, in group order.
+   * @default undefined — every outline is drawn at full strength
+   */
+  opacities?: readonly number[];
+  /**
+   * How solid each region is; `0` draws nothing at all, since the fill is the
+   * whole outline. Turn it down when many groups overlap, since the fills
+   * compound.
+   * @default SCATTER_OUTLINE_FILL_OPACITY
+   */
+  fillOpacity?: number;
+  /**
+   * Called with the groups too small to outline, as indices into `colors`,
+   * whenever that set changes. An outline that quietly fails to appear reads
+   * as a bug in the plot, so the caller is handed what its caption has to
+   * account for.
+   * @default undefined
+   */
+  onSkippedGroups?: (groups: readonly number[]) => void;
+}
+
+/**
+ * One outline per group, drawn through both scales.
+ *
+ * The outline is measured in the data's own units and drawn in pixels, and the
+ * two axes almost never carry the same number of units per pixel — so scaling
+ * the two radii and keeping the data-space angle would draw an ellipse of the
+ * wrong shape at the wrong tilt. `scatterOutlineShape` transforms the spread
+ * first and decomposes it after, which is exact on a linear axis.
+ *
+ * The outlines are drawn under the dots, which is what lets the region be
+ * filled at all: the fill says where a group sits without taking the dots the
+ * reader is there to count.
+ * @param props - See {@link ScatterEllipseLayerProps}.
+ * @returns The outlines.
+ */
+export const ScatterEllipseLayer = memo(function ScatterEllipseLayer(
+  props: ScatterEllipseLayerProps,
+): ReactElement {
+  const {
+    x,
+    y,
+    groupOf,
+    colors,
+    scaleX,
+    scaleY,
+    size = DEFAULT_SIZE,
+    minimumPoints = 3,
+    opacities,
+    fillOpacity,
+    onSkippedGroups,
+  } = props;
+
+  const clouds = groupClouds(x, y, groupOf, colors.length);
+  const outlines: ReactElement[] = [];
+  const skipped: number[] = [];
+  for (let group = 0; group < clouds.length; group++) {
+    const color = colors[group];
+    const cloud = clouds[group];
+    if (color === undefined || cloud === undefined) continue;
+    const measured = confidenceEllipse(cloud, { size, minimumPoints });
+    if (measured === null) {
+      skipped.push(group);
+      continue;
+    }
+    const ink = { color, opacity: opacities?.[group], fillOpacity };
+    outlines.push(scatterOutlineShape(group, measured, scaleX, scaleY, ink));
+  }
+
+  useSkippedReport(skipped, onSkippedGroups);
+  return <g data-layer="ellipses">{outlines}</g>;
+});
+
+/** What a group is outlined at when the caller says nothing. */
+const DEFAULT_SIZE: EllipseSize = { kind: 'coverage', probability: 0.95 };
+
+/* Each group's points, gathered once so every group is measured in one pass. */
+function groupClouds(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  groupOf: ArrayLike<number>,
+  groups: number,
+): EllipsePoint[][] {
+  const clouds: EllipsePoint[][] = new Array(groups);
+  for (let group = 0; group < groups; group++) clouds[group] = [];
+  const total = Math.min(x.length, y.length, groupOf.length);
+  for (let index = 0; index < total; index++) {
+    const group = groupOf[index];
+    if (group === undefined || group < 0 || group >= groups) continue;
+    const px = x[index];
+    const py = y[index];
+    if (px === undefined || py === undefined) continue;
+    clouds[group]?.push({ x: px, y: py });
+  }
+  return clouds;
+}
+
+/*
+ * Report the skipped groups once each time the set changes. A fresh array is
+ * built every render, so it is the joined indices that are compared and not
+ * the array, which is what keeps a caller storing the answer from re-rendering
+ * for ever.
+ */
+function useSkippedReport(
+  skipped: readonly number[],
+  report: ((groups: readonly number[]) => void) | undefined,
+): void {
+  const last = useRef('');
+  const key = skipped.join(' ');
+  useEffect(() => {
+    if (last.current === key) return;
+    last.current = key;
+    report?.(skipped);
+  });
+}