@oxyhq/bloom 0.34.3 → 0.35.0

package/src/avatar-group/AvatarGroupBase.tsx

@@ -4,12 +4,15 @@ import {
   StyleSheet,
   Text,
   View,
+  type StyleProp,
+  type TextStyle,
   type ViewStyle,
 } from 'react-native';
 
 import { Avatar } from '../avatar';
 import { useTheme } from '../theme/use-theme';
 import { fontSize } from '../styles/tokens';
+import { computeClusterLayout } from './cluster-layout';
 import type { AvatarGroupItem, AvatarGroupProps } from './types';
 
 /** Ring (border) thickness around each avatar, in pixels. Matches the
@@ -18,6 +21,15 @@ const RING_WIDTH = 1;
 /** Default horizontal overlap as a fraction of avatar size — the original
  * stack pulled each avatar left by `size / 3`. */
 const DEFAULT_OVERLAP_RATIO = 1 / 3;
+/** Default `max` for the `stack`/`row` facepile layouts. */
+const DEFAULT_MAX = 5;
+/** Default `max` (visible cap) for the `cluster` layout — it packs densely. */
+const CLUSTER_DEFAULT_MAX = 20;
+/** Separator ring thickness for cluster bubbles, as a fraction of the box. */
+const CLUSTER_RING_RATIO = 0.02;
+/** Overflow "+N" text color — white reads on the grey chip in light + dark,
+ * matching the original Mention count circle (shared by every layout). */
+const OVERFLOW_TEXT_COLOR = '#FFFFFF';
 
 function getItemName(item: AvatarGroupItem): string | undefined {
   return item.displayName ?? item.name ?? item.username;
@@ -39,12 +51,103 @@ interface AvatarGroupBaseProps extends AvatarGroupProps {
   hoverHandlers?: AvatarGroupCellHoverHandlers;
 }
 
+/**
+ * A single avatar cell shared by every layout: a circular, clipped container
+ * (`cellStyle`) holding one {@link Avatar}, positioned by `wrapperStyle`, and
+ * made pressable/hoverable when the relevant handlers are supplied. Layout
+ * (margins for the facepile, absolute coords for the cluster) lives entirely in
+ * the caller-provided styles so this stays layout-agnostic.
+ */
+function AvatarGroupCell({
+  item,
+  index,
+  innerSize,
+  variant,
+  showInitials,
+  cellStyle,
+  wrapperStyle,
+  onPressItem,
+  hoverHandlers,
+}: {
+  item: AvatarGroupItem;
+  index: number;
+  innerSize: number;
+  variant?: string;
+  showInitials: boolean;
+  cellStyle: StyleProp<ViewStyle>;
+  wrapperStyle: StyleProp<ViewStyle>;
+  onPressItem?: (item: AvatarGroupItem, index: number) => void;
+  hoverHandlers?: AvatarGroupCellHoverHandlers;
+}) {
+  const name = getItemName(item);
+  const accessibilityLabel = item.username
+    ? `${name ?? item.username} (@${item.username})`
+    : name;
+  const interactive = typeof onPressItem === 'function';
+  const hoverable =
+    typeof hoverHandlers?.onHoverIn === 'function' ||
+    typeof hoverHandlers?.onHoverOut === 'function';
+
+  const cell = (
+    <View
+      ref={
+        hoverHandlers?.registerCellRef
+          ? (node) => hoverHandlers.registerCellRef?.(index, node)
+          : undefined
+      }
+      collapsable={false}
+      style={cellStyle}
+    >
+      {/*
+        Route the item's avatar value through Avatar's `source` prop (not `uri`):
+        full URLs pass through directly, while resolver-handled ids (e.g. Oxy
+        file IDs) are resolved by the consumer's ImageResolver. `variant`
+        (default `'thumb'`) is forwarded so the resolver builds a small rendition.
+        A missing avatar shows Avatar's neutral default placeholder unless
+        `showInitials` is set, in which case the item's name renders a colored
+        initial.
+      */}
+      <Avatar
+        source={item.uri ?? undefined}
+        name={showInitials ? name : undefined}
+        variant={variant}
+        size={innerSize}
+      />
+    </View>
+  );
+
+  if (interactive || hoverable) {
+    return (
+      <Pressable
+        onPress={interactive ? () => onPressItem?.(item, index) : undefined}
+        onHoverIn={
+          hoverHandlers?.onHoverIn
+            ? () => hoverHandlers.onHoverIn?.(item, index)
+            : undefined
+        }
+        onHoverOut={
+          hoverHandlers?.onHoverOut
+            ? () => hoverHandlers.onHoverOut?.(item, index)
+            : undefined
+        }
+        accessibilityRole={interactive ? 'button' : undefined}
+        accessibilityLabel={accessibilityLabel}
+        style={wrapperStyle}
+      >
+        {cell}
+      </Pressable>
+    );
+  }
+
+  return <View style={wrapperStyle}>{cell}</View>;
+}
+
 const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   items,
   layout = 'stack',
   size = 32,
   variant = 'thumb',
-  max = 5,
+  max,
   total,
   overlap,
   spacing,
@@ -56,6 +159,7 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   hoverHandlers,
 }) => {
   const theme = useTheme();
+  const isCluster = layout === 'cluster';
   const isRow = layout === 'row';
 
   // The ring is the thin separator drawn between overlapping avatars. It
@@ -63,6 +167,8 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   // the surface behind them — matching the original Mention stack, which used
   // `theme.colors.background`, not a large `card`-colored ring cell.
   const ring = ringColor ?? theme.colors.background;
+
+  const effectiveMax = max ?? DEFAULT_MAX;
   const effectiveOverlap =
     overlap ?? Math.round(size * DEFAULT_OVERLAP_RATIO);
   // Each avatar after the first is pulled left by `overlap`. The cell carries a
@@ -75,8 +181,8 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   const itemMargin = isRow ? rowGap : negativeMargin;
 
   const shown = useMemo(
-    () => items.slice(0, Math.max(0, max)),
-    [items, max],
+    () => items.slice(0, Math.max(0, effectiveMax)),
+    [items, effectiveMax],
   );
 
   const realTotal = total ?? items.length;
@@ -109,18 +215,15 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   }, [isRow, size, ring]);
 
   const overflowTextStyle = useMemo(
-    () => ({
-      color: '#FFFFFF',
+    (): TextStyle => ({
+      color: OVERFLOW_TEXT_COLOR,
       fontSize: Math.max(fontSize._2xs, Math.round(size * 0.36)),
-      fontWeight: '600' as const,
+      fontWeight: '600',
     }),
     [size],
   );
 
   const interactive = typeof onPressItem === 'function';
-  const hoverable =
-    typeof hoverHandlers?.onHoverIn === 'function' ||
-    typeof hoverHandlers?.onHoverOut === 'function';
 
   // Pressing the "+N" circle surfaces the first hidden member (if any), so
   // consumers can route it to a full member list.
@@ -130,14 +233,29 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
       ? () => onPressItem?.(firstHidden, shown.length)
       : undefined;
 
+  // The cluster is a compact 2D bubble pack with its own absolute-positioned
+  // renderer; hooks above still run unconditionally so the branch is safe.
+  if (isCluster) {
+    return (
+      <ClusterAvatarGroup
+        items={items}
+        size={size}
+        variant={variant}
+        max={max}
+        total={total}
+        ring={ring}
+        showInitials={showInitials}
+        onPressItem={onPressItem}
+        style={style}
+        testID={testID}
+        hoverHandlers={hoverHandlers}
+      />
+    );
+  }
+
   return (
     <View style={[styles.row, style]} testID={testID}>
       {shown.map((item, index) => {
-        const name = getItemName(item);
-        const accessibilityLabel = item.username
-          ? `${name ?? item.username} (@${item.username})`
-          : name;
-
         // The horizontal margin and stacking order live on the outermost row
         // element so layout and hit-testing stay aligned with the visual
         // overlap. In stack mode earlier siblings render on top of later ones
@@ -148,66 +266,19 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
           ...(isRow ? {} : { zIndex: shown.length - index }),
         };
 
-        const cell = (
-          <View
-            ref={
-              hoverHandlers?.registerCellRef
-                ? (node) => hoverHandlers.registerCellRef?.(index, node)
-                : undefined
-            }
-            collapsable={false}
-            style={cellStyle}
-          >
-            {/*
-              Route the item's avatar value through Avatar's `source` prop (not
-              `uri`): full URLs pass through directly, while resolver-handled ids
-              (e.g. Oxy file IDs) are resolved by the consumer's ImageResolver —
-              exactly like the original Mention stack. `variant` (default
-              `'thumb'`) is forwarded so the resolver builds a small rendition
-              for these stacked avatars. No `name` is passed, so a missing
-              avatar shows Avatar's neutral default placeholder rather than a
-              colored deterministic initial. When `showInitials` is set the item's
-              name IS passed, so an avatar-less item renders a colored initial.
-            */}
-            <Avatar
-              source={item.uri ?? undefined}
-              name={showInitials ? name : undefined}
-              variant={variant}
-              size={innerSize}
-            />
-          </View>
-        );
-
-        if (interactive || hoverable) {
-          return (
-            <Pressable
-              key={getItemKey(item, index)}
-              onPress={
-                interactive ? () => onPressItem?.(item, index) : undefined
-              }
-              onHoverIn={
-                hoverHandlers?.onHoverIn
-                  ? () => hoverHandlers.onHoverIn?.(item, index)
-                  : undefined
-              }
-              onHoverOut={
-                hoverHandlers?.onHoverOut
-                  ? () => hoverHandlers.onHoverOut?.(item, index)
-                  : undefined
-              }
-              accessibilityRole={interactive ? 'button' : undefined}
-              accessibilityLabel={accessibilityLabel}
-              style={wrapperStyle}
-            >
-              {cell}
-            </Pressable>
-          );
-        }
-
         return (
-          <View key={getItemKey(item, index)} style={wrapperStyle}>
-            {cell}
-          </View>
+          <AvatarGroupCell
+            key={getItemKey(item, index)}
+            item={item}
+            index={index}
+            innerSize={innerSize}
+            variant={variant}
+            showInitials={showInitials}
+            cellStyle={cellStyle}
+            wrapperStyle={wrapperStyle}
+            onPressItem={onPressItem}
+            hoverHandlers={hoverHandlers}
+          />
         );
       })}
 
@@ -215,8 +286,10 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
         <OverflowCircle
           count={overflow}
           cellStyle={cellStyle}
-          marginLeft={shown.length > 0 ? itemMargin : 0}
-          isRow={isRow}
+          wrapperStyle={{
+            ...(shown.length > 0 && { marginLeft: itemMargin }),
+            ...(isRow ? {} : { zIndex: 0 }),
+          }}
           textStyle={overflowTextStyle}
           onPress={overflowOnPress}
         />
@@ -225,32 +298,168 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   );
 };
 
+interface ClusterAvatarGroupProps {
+  items: AvatarGroupItem[];
+  size: number;
+  variant?: string;
+  max?: number;
+  total?: number;
+  ring: string;
+  showInitials: boolean;
+  onPressItem?: (item: AvatarGroupItem, index: number) => void;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  hoverHandlers?: AvatarGroupCellHoverHandlers;
+}
+
+/**
+ * The `cluster` layout: an iMessage-style magnetic bubble pack. Members are laid
+ * out by {@link computeClusterLayout} (a deterministic force-directed pack) into
+ * box-fraction bubbles, then absolutely positioned inside a `size × size` box so
+ * the whole cluster drops in where a single round Avatar would. The largest
+ * member (index 0) sits centred and in front; the rest pack around it with a
+ * uniform gap. Overflow beyond `max` collapses into a trailing "+N" bubble.
+ */
+const ClusterAvatarGroup: React.FC<ClusterAvatarGroupProps> = ({
+  items,
+  size,
+  variant,
+  max,
+  total,
+  ring,
+  showInitials,
+  onPressItem,
+  style,
+  testID,
+  hoverHandlers,
+}) => {
+  const cap = Math.max(1, max ?? CLUSTER_DEFAULT_MAX);
+  const realTotal = total ?? items.length;
+  const hasOverflow = realTotal > cap;
+  // Reserve the last bubble for the "+N" chip when there are more members than
+  // the cap; otherwise every capped member gets its own bubble.
+  const avatarCap = hasOverflow ? Math.max(0, cap - 1) : cap;
+  const shown = useMemo(
+    () => items.slice(0, avatarCap),
+    [items, avatarCap],
+  );
+  const overflow = hasOverflow ? Math.max(0, realTotal - shown.length) : 0;
+  const bubbleCount = shown.length + (overflow > 0 ? 1 : 0);
+  const bubbles = useMemo(
+    () => computeClusterLayout(bubbleCount),
+    [bubbleCount],
+  );
+
+  const ringWidth = Math.max(1, Math.round(size * CLUSTER_RING_RATIO));
+  const interactive = typeof onPressItem === 'function';
+
+  // Pressing "+N" surfaces the first hidden member (parity with the stack).
+  const firstHidden = items[shown.length];
+  const overflowOnPress =
+    interactive && firstHidden
+      ? () => onPressItem?.(firstHidden, shown.length)
+      : undefined;
+
+  const overflowBubble = overflow > 0 ? bubbles[bubbleCount - 1] : undefined;
+  let overflowElement: React.ReactNode = null;
+  if (overflow > 0 && overflowBubble) {
+    const diameter = overflowBubble.d * size;
+    overflowElement = (
+      <OverflowCircle
+        count={overflow}
+        cellStyle={{
+          width: diameter,
+          height: diameter,
+          borderRadius: diameter / 2,
+          borderWidth: ringWidth,
+          borderColor: ring,
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+        wrapperStyle={{
+          position: 'absolute',
+          left: overflowBubble.cx * size - diameter / 2,
+          top: overflowBubble.cy * size - diameter / 2,
+          width: diameter,
+          height: diameter,
+          zIndex: 0,
+        }}
+        textStyle={{
+          color: OVERFLOW_TEXT_COLOR,
+          fontSize: Math.max(fontSize._2xs, Math.round(diameter * 0.34)),
+          fontWeight: '600',
+        }}
+        onPress={overflowOnPress}
+      />
+    );
+  }
+
+  return (
+    <View style={[{ width: size, height: size }, style]} testID={testID}>
+      {shown.map((item, index) => {
+        const bubble = bubbles[index];
+        if (!bubble) return null;
+        const diameter = bubble.d * size;
+        const inner = Math.max(1, diameter - ringWidth * 2);
+        const wrapperStyle: ViewStyle = {
+          position: 'absolute',
+          left: bubble.cx * size - diameter / 2,
+          top: bubble.cy * size - diameter / 2,
+          width: diameter,
+          height: diameter,
+          // Primary (index 0) is largest and sits in front; later members tuck
+          // behind in descending order (the "+N" chip lands lowest).
+          zIndex: bubbleCount - index,
+        };
+        const cellStyle: ViewStyle = {
+          width: diameter,
+          height: diameter,
+          borderRadius: diameter / 2,
+          borderWidth: ringWidth,
+          borderColor: ring,
+          overflow: 'hidden',
+          alignItems: 'center',
+          justifyContent: 'center',
+        };
+        return (
+          <AvatarGroupCell
+            key={getItemKey(item, index)}
+            item={item}
+            index={index}
+            innerSize={inner}
+            variant={variant}
+            showInitials={showInitials}
+            cellStyle={cellStyle}
+            wrapperStyle={wrapperStyle}
+            onPressItem={onPressItem}
+            hoverHandlers={hoverHandlers}
+          />
+        );
+      })}
+      {overflowElement}
+    </View>
+  );
+};
+
 function OverflowCircle({
   count,
   cellStyle,
-  marginLeft,
-  isRow,
+  wrapperStyle,
   textStyle,
   onPress,
 }: {
   count: number;
-  cellStyle: ViewStyle;
-  marginLeft: number;
-  isRow: boolean;
-  textStyle: { color: string; fontSize: number; fontWeight: '600' };
+  cellStyle: StyleProp<ViewStyle>;
+  wrapperStyle: StyleProp<ViewStyle>;
+  textStyle: TextStyle;
   onPress?: () => void;
 }) {
   const theme = useTheme();
-  // In stack mode the count circle is anchored at the lowest stacking order so
-  // it tucks behind the last avatar's ring; row mode has no overlap. The margin
-  // lives on the outer element to keep layout aligned with the spacing.
-  const wrapperStyle: ViewStyle = {
-    ...(marginLeft !== 0 && { marginLeft }),
-    ...(isRow ? {} : { zIndex: 0 }),
-  };
 
   // A solid "+N" count circle: secondary-text-colored fill with white text,
-  // matching the original Mention `ResponsiveAvatarStack` count circle.
+  // matching the original Mention `ResponsiveAvatarStack` count circle. Layout
+  // (margin for the facepile, absolute coords for the cluster) is supplied by
+  // the caller via `wrapperStyle`.
   const circle = (
     <View
       style={[cellStyle, { backgroundColor: theme.colors.textSecondary }]}

package/src/avatar-group/cluster-layout.ts

@@ -0,0 +1,204 @@
+/**
+ * Deterministic organic circle-packing for the {@link AvatarGroup} `cluster`
+ * layout — the iMessage-style "magnetic bubble cluster" where several avatars of
+ * varying sizes nestle together inside a round bounding box (a large primary in
+ * the middle/front, smaller members packed around it with a uniform gap).
+ *
+ * For 4+ members the layout is produced by a small, FULLY DETERMINISTIC
+ * force-directed relaxation (no `Math.random`): the primary is pinned at the
+ * centre and the remaining members are seeded on a golden-angle spiral, then a
+ * fixed number of relaxation passes (a) pull every non-primary circle toward the
+ * centre and (b) push any two circles apart until they clear a uniform gap. A
+ * fixed iteration count + deterministic seed means the same `count` always
+ * yields byte-identical positions, so native and web render the cluster
+ * identically with no `onLayout`/DOM measurement. The very small counts (1, 2,
+ * 3) — where a relaxation degenerates into a line or a lone pair — use explicit
+ * iMessage-style arrangements instead.
+ *
+ * Output is resolution-independent: each bubble is expressed as a fraction of
+ * the group's bounding box (`cx`/`cy` centre, `d` diameter, all 0..1), so the
+ * consumer just multiplies by the pixel `size`. Every bubble is guaranteed to
+ * sit fully inside the `[0, 1]` box (the packed result is scaled + translated to
+ * fit), so the cluster drops in exactly where a single round Avatar would.
+ */
+
+/** A single packed bubble, expressed as fractions of the bounding box (0..1). */
+export interface ClusterBubble {
+  /** Centre X as a fraction of the box width. */
+  cx: number;
+  /** Centre Y as a fraction of the box height. */
+  cy: number;
+  /** Diameter as a fraction of the box size. */
+  d: number;
+}
+
+// Golden angle (~137.5°) — spreads the seed points evenly with no directional
+// bias, which is what gives the relaxed result its organic, non-grid feel.
+const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5));
+// Fixed relaxation passes + a final separation-only cleanup so the last thing
+// that happens is overlap resolution (gaps end uniform and non-negative).
+const ITERATIONS = 500;
+const CLEANUP_ITERATIONS = 80;
+// How hard each pass pulls every non-primary circle toward the centre. This is
+// the only compacting force; separation only ever pushes apart, so any positive
+// value packs the cluster fully — this just controls convergence speed.
+const CENTERING = 0.05;
+// Fraction of an overlap resolved per pass. 1 fully separates each pass; with
+// the pinned primary and many passes this stays stable and converges.
+const SEPARATION_STRENGTH = 1;
+// Uniform gap kept between every touching pair, in primary-radius units
+// (primary radius = 1). Reads as consistent spacing everywhere in the cluster.
+const LAYOUT_GAP = 0.16;
+// Initial spiral spacing. Only affects convergence (the result is re-fitted to
+// the box afterwards), not the final scale.
+const SEED_SPACING = 1.7;
+// Relative radii: the primary is the largest; the remaining members taper from
+// SECONDARY_MAX (nearest the primary) down to SECONDARY_MIN (outermost) so size
+// decreases outward and later/overflow members are the smallest.
+const PRIMARY_RADIUS = 1;
+const SECONDARY_MAX = 0.72;
+const SECONDARY_MIN = 0.5;
+const EPSILON = 1e-6;
+
+/** Relative radius for member `index` of a `count`-member cluster. */
+function relativeRadius(index: number, count: number): number {
+  if (index === 0) return PRIMARY_RADIUS;
+  if (count <= 2) return SECONDARY_MAX;
+  const t = (index - 1) / (count - 2);
+  return SECONDARY_MAX + (SECONDARY_MIN - SECONDARY_MAX) * t;
+}
+
+/**
+ * One separation pass: push any pair closer than `(r_i + r_j + gap)` apart. The
+ * primary (index 0) is pinned — when a pair involves it, only the other circle
+ * moves — which keeps the largest avatar dead-centre and in front.
+ */
+function separate(xs: number[], ys: number[], radii: number[], count: number): void {
+  for (let i = 0; i < count; i++) {
+    for (let j = i + 1; j < count; j++) {
+      let dx = (xs[j] ?? 0) - (xs[i] ?? 0);
+      let dy = (ys[j] ?? 0) - (ys[i] ?? 0);
+      let dist = Math.hypot(dx, dy);
+      const minDist = (radii[i] ?? 0) + (radii[j] ?? 0) + LAYOUT_GAP;
+      if (dist >= minDist) continue;
+      if (dist < EPSILON) {
+        // Coincident points: pick a deterministic direction from the indices so
+        // the split is stable (never random).
+        const a = (i + 1) * GOLDEN_ANGLE + j;
+        dx = Math.cos(a);
+        dy = Math.sin(a);
+        dist = 1;
+      }
+      const overlap = (minDist - dist) * SEPARATION_STRENGTH;
+      const nx = dx / dist;
+      const ny = dy / dist;
+      if (i === 0) {
+        // Primary pinned: move only the other circle by the full overlap.
+        xs[j] = (xs[j] ?? 0) + nx * overlap;
+        ys[j] = (ys[j] ?? 0) + ny * overlap;
+      } else {
+        xs[i] = (xs[i] ?? 0) - (nx * overlap) / 2;
+        ys[i] = (ys[i] ?? 0) - (ny * overlap) / 2;
+        xs[j] = (xs[j] ?? 0) + (nx * overlap) / 2;
+        ys[j] = (ys[j] ?? 0) + (ny * overlap) / 2;
+      }
+    }
+  }
+}
+
+/**
+ * Deterministic force-directed pack of `count` circles (primary pinned at the
+ * centre), returned as box-fraction bubbles. Used for every cluster with 4+
+ * members; 1–3 are handled as explicit arrangements in
+ * {@link computeClusterLayout}.
+ */
+function packCluster(count: number): ClusterBubble[] {
+  const radii = new Array<number>(count);
+  const xs = new Array<number>(count);
+  const ys = new Array<number>(count);
+
+  for (let i = 0; i < count; i++) {
+    radii[i] = relativeRadius(i, count);
+    if (i === 0) {
+      xs[i] = 0;
+      ys[i] = 0;
+    } else {
+      // Golden-angle spiral seed around the pinned primary.
+      const seedR = SEED_SPACING * Math.sqrt(i);
+      const angle = i * GOLDEN_ANGLE;
+      xs[i] = seedR * Math.cos(angle);
+      ys[i] = seedR * Math.sin(angle);
+    }
+  }
+
+  for (let iter = 0; iter < ITERATIONS; iter++) {
+    // (a) Centering: pull every non-primary circle toward the centre.
+    for (let i = 1; i < count; i++) {
+      xs[i] = (xs[i] ?? 0) * (1 - CENTERING);
+      ys[i] = (ys[i] ?? 0) * (1 - CENTERING);
+    }
+    // (b) Separation resolves any resulting overlaps (primary stays pinned).
+    separate(xs, ys, radii, count);
+    xs[0] = 0;
+    ys[0] = 0;
+  }
+  // Final separation-only passes so the cluster ends with clean uniform gaps.
+  for (let iter = 0; iter < CLEANUP_ITERATIONS; iter++) {
+    separate(xs, ys, radii, count);
+    xs[0] = 0;
+    ys[0] = 0;
+  }
+
+  // Fit to the unit box: the primary is at the origin, so scale so the
+  // outermost circle edge lands on the box radius (0.5) and place the primary at
+  // the box centre.
+  let bound = 0;
+  for (let i = 0; i < count; i++) {
+    const reach = Math.hypot(xs[i] ?? 0, ys[i] ?? 0) + (radii[i] ?? 0);
+    if (reach > bound) bound = reach;
+  }
+  const scale = bound > EPSILON ? 0.5 / bound : 0.5;
+
+  const bubbles = new Array<ClusterBubble>(count);
+  for (let i = 0; i < count; i++) {
+    bubbles[i] = {
+      cx: 0.5 + (xs[i] ?? 0) * scale,
+      cy: 0.5 + (ys[i] ?? 0) * scale,
+      d: 2 * (radii[i] ?? 0) * scale,
+    };
+  }
+  return bubbles;
+}
+
+/**
+ * Deterministic cluster layout for `count` bubbles, as box-fraction bubbles
+ * ordered primary-first. `count` includes the `+N` overflow bubble when present
+ * (it is simply the last, smallest member of the pack).
+ *
+ * - `<= 0` → empty.
+ * - `1` → a single bubble filling the box.
+ * - `2` → the iMessage "one in front, one behind" pair: a larger primary set
+ *   low-left with a smaller member tucked behind it to the upper-right.
+ * - `3` → an iMessage-style triangle: the larger primary along the bottom with
+ *   two smaller members above it.
+ * - `4+` → the deterministic force-directed pack (primary centred, the rest
+ *   packed magnetically around it, denser as the count grows).
+ */
+export function computeClusterLayout(count: number): ClusterBubble[] {
+  if (count <= 0) return [];
+  if (count === 1) return [{ cx: 0.5, cy: 0.5, d: 1 }];
+  if (count === 2) {
+    return [
+      { cx: 0.42, cy: 0.56, d: 0.66 },
+      { cx: 0.68, cy: 0.36, d: 0.5 },
+    ];
+  }
+  if (count === 3) {
+    return [
+      { cx: 0.5, cy: 0.69, d: 0.54 },
+      { cx: 0.285, cy: 0.24, d: 0.4 },
+      { cx: 0.715, cy: 0.24, d: 0.4 },
+    ];
+  }
+  return packCluster(count);
+}