@oxyhq/bloom 0.34.3 → 0.35.1

package/lib/commonjs/avatar-group/cluster-layout.js

@@ -0,0 +1,252 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.computeClusterLayout = computeClusterLayout;
+/**
+ * Deterministic organic circle-packing for the {@link AvatarGroup} `cluster`
+ * layout — the iMessage-style "magnetic bubble cluster" where several avatars of
+ * NEAR-EQUAL size nestle tightly together and fill a round bounding box (a
+ * modestly larger primary with the rest only slightly smaller, packed against
+ * each other with a small uniform gap — not a big primary ringed by tiny dots).
+ *
+ * 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`. The relaxed blob is recentred on
+ * its own centre and scaled so the outermost bubble edge lands on the box edge,
+ * so it fills the round box densely with minimal empty margin while every bubble
+ * is guaranteed to sit fully inside the `[0, 1]` box — the cluster drops in
+ * exactly where a single round Avatar would.
+ */
+
+/** A single packed bubble, expressed as fractions of the bounding box (0..1). */
+
+// 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). Small, so near-equal bubbles nestle tightly like
+// magnets rather than floating apart with visible margins.
+const LAYOUT_GAP = 0.12;
+// 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 only MODESTLY the largest; every other member
+// tapers gently from SECONDARY_MAX (nearest the primary) down to SECONDARY_MIN
+// (outermost). The spread is deliberately narrow so the cluster reads as a pack
+// of near-equal magnetic bubbles — a slightly larger primary, not a big primary
+// ringed by tiny dots.
+const PRIMARY_RADIUS = 1;
+const SECONDARY_MAX = 0.9;
+const SECONDARY_MIN = 0.8;
+const EPSILON = 1e-6;
+
+/** Relative radius for member `index` of a `count`-member cluster. */
+function relativeRadius(index, count) {
+  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, ys, radii, count) {
+  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) {
+  const radii = new Array(count);
+  const xs = new Array(count);
+  const ys = new Array(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 so the pack FILLS the round box edge-to-edge with
+  // minimal empty margin. The primary was pinned at the origin during
+  // relaxation, but the relaxed blob is not centred on it, so we recentre on the
+  // cluster's OWN centre (its bounding-box midpoint) rather than the primary:
+  // enclose every bubble in a circle around that centre, then scale so the
+  // outermost bubble edge lands exactly on the box radius (0.5). Centring the
+  // enclosing circle at the box centre keeps every bubble inside the [0, 1] box
+  // (the enclosing circle is inscribed in the square) while packing the blob
+  // tightly against the edge instead of floating with a gap.
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i < count; i++) {
+    const x = xs[i] ?? 0;
+    const y = ys[i] ?? 0;
+    const r = radii[i] ?? 0;
+    if (x - r < minX) minX = x - r;
+    if (x + r > maxX) maxX = x + r;
+    if (y - r < minY) minY = y - r;
+    if (y + r > maxY) maxY = y + r;
+  }
+  const centerX = (minX + maxX) / 2;
+  const centerY = (minY + maxY) / 2;
+  let bound = 0;
+  for (let i = 0; i < count; i++) {
+    const reach = Math.hypot((xs[i] ?? 0) - centerX, (ys[i] ?? 0) - centerY) + (radii[i] ?? 0);
+    if (reach > bound) bound = reach;
+  }
+  const scale = bound > EPSILON ? 0.5 / bound : 0.5;
+  const bubbles = new Array(count);
+  for (let i = 0; i < count; i++) {
+    bubbles[i] = {
+      cx: 0.5 + ((xs[i] ?? 0) - centerX) * scale,
+      cy: 0.5 + ((ys[i] ?? 0) - centerY) * 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: two EQUAL-diameter
+ *   bubbles offset on a diagonal — the front set low-left, the other tucked
+ *   behind it to the upper-right. Same radius, so neither member reads as
+ *   secondary; the overlap + separator ring alone convey the stacking.
+ * - `3` → an iMessage-style triangle: the larger primary along the bottom with
+ *   two smaller members above it.
+ * - `4+` → the deterministic force-directed pack of near-equal bubbles, recentred
+ *   and scaled to fill the round box edge-to-edge (a modestly larger primary near
+ *   the centre, the rest packed magnetically around it, denser as the count
+ *   grows).
+ */
+function computeClusterLayout(count) {
+  if (count <= 0) return [];
+  if (count === 1) return [{
+    cx: 0.5,
+    cy: 0.5,
+    d: 1
+  }];
+  if (count === 2) {
+    // Two EQUAL-diameter bubbles, offset symmetrically on the diagonal: the
+    // front (index 0, highest zIndex) sits low-left, the other tucks behind it
+    // to the upper-right. They overlap (the intentional "front + behind" pair);
+    // the separator ring — not a size difference — reads the stacking.
+    return [{
+      cx: 0.35,
+      cy: 0.65,
+      d: 0.64
+    }, {
+      cx: 0.65,
+      cy: 0.35,
+      d: 0.64
+    }];
+  }
+  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);
+}
+//# sourceMappingURL=cluster-layout.js.map

package/lib/commonjs/avatar-group/cluster-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GOLDEN_ANGLE","Math","PI","sqrt","ITERATIONS","CLEANUP_ITERATIONS","CENTERING","SEPARATION_STRENGTH","LAYOUT_GAP","SEED_SPACING","PRIMARY_RADIUS","SECONDARY_MAX","SECONDARY_MIN","EPSILON","relativeRadius","index","count","t","separate","xs","ys","radii","i","j","dx","dy","dist","hypot","minDist","a","cos","sin","overlap","nx","ny","packCluster","Array","seedR","angle","iter","minX","Infinity","maxX","minY","maxY","x","y","r","centerX","centerY","bound","reach","scale","bubbles","cx","cy","d","computeClusterLayout"],"sourceRoot":"../../../src","sources":["avatar-group/cluster-layout.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAUA;AACA;AACA,MAAMA,YAAY,GAAGC,IAAI,CAACC,EAAE,IAAI,CAAC,GAAGD,IAAI,CAACE,IAAI,CAAC,CAAC,CAAC,CAAC;AACjD;AACA;AACA,MAAMC,UAAU,GAAG,GAAG;AACtB,MAAMC,kBAAkB,GAAG,EAAE;AAC7B;AACA;AACA;AACA,MAAMC,SAAS,GAAG,IAAI;AACtB;AACA;AACA,MAAMC,mBAAmB,GAAG,CAAC;AAC7B;AACA;AACA;AACA,MAAMC,UAAU,GAAG,IAAI;AACvB;AACA;AACA,MAAMC,YAAY,GAAG,GAAG;AACxB;AACA;AACA;AACA;AACA;AACA,MAAMC,cAAc,GAAG,CAAC;AACxB,MAAMC,aAAa,GAAG,GAAG;AACzB,MAAMC,aAAa,GAAG,GAAG;AACzB,MAAMC,OAAO,GAAG,IAAI;;AAEpB;AACA,SAASC,cAAcA,CAACC,KAAa,EAAEC,KAAa,EAAU;EAC5D,IAAID,KAAK,KAAK,CAAC,EAAE,OAAOL,cAAc;EACtC,IAAIM,KAAK,IAAI,CAAC,EAAE,OAAOL,aAAa;EACpC,MAAMM,CAAC,GAAG,CAACF,KAAK,GAAG,CAAC,KAAKC,KAAK,GAAG,CAAC,CAAC;EACnC,OAAOL,aAAa,GAAG,CAACC,aAAa,GAAGD,aAAa,IAAIM,CAAC;AAC5D;;AAEA;AACA;AACA;AACA;AACA;AACA,SAASC,QAAQA,CAACC,EAAY,EAAEC,EAAY,EAAEC,KAAe,EAAEL,KAAa,EAAQ;EAClF,KAAK,IAAIM,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,KAAK,EAAEM,CAAC,EAAE,EAAE;IAC9B,KAAK,IAAIC,CAAC,GAAGD,CAAC,GAAG,CAAC,EAAEC,CAAC,GAAGP,KAAK,EAAEO,CAAC,EAAE,EAAE;MAClC,IAAIC,EAAE,GAAG,CAACL,EAAE,CAACI,CAAC,CAAC,IAAI,CAAC,KAAKJ,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,CAAC;MACpC,IAAIG,EAAE,GAAG,CAACL,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,KAAKH,EAAE,CAACE,CAAC,CAAC,IAAI,CAAC,CAAC;MACpC,IAAII,IAAI,GAAGzB,IAAI,CAAC0B,KAAK,CAACH,EAAE,EAAEC,EAAE,CAAC;MAC7B,MAAMG,OAAO,GAAG,CAACP,KAAK,CAACC,CAAC,CAAC,IAAI,CAAC,KAAKD,KAAK,CAACE,CAAC,CAAC,IAAI,CAAC,CAAC,GAAGf,UAAU;MAC9D,IAAIkB,IAAI,IAAIE,OAAO,EAAE;MACrB,IAAIF,IAAI,GAAGb,OAAO,EAAE;QAClB;QACA;QACA,MAAMgB,CAAC,GAAG,CAACP,CAAC,GAAG,CAAC,IAAItB,YAAY,GAAGuB,CAAC;QACpCC,EAAE,GAAGvB,IAAI,CAAC6B,GAAG,CAACD,CAAC,CAAC;QAChBJ,EAAE,GAAGxB,IAAI,CAAC8B,GAAG,CAACF,CAAC,CAAC;QAChBH,IAAI,GAAG,CAAC;MACV;MACA,MAAMM,OAAO,GAAG,CAACJ,OAAO,GAAGF,IAAI,IAAInB,mBAAmB;MACtD,MAAM0B,EAAE,GAAGT,EAAE,GAAGE,IAAI;MACpB,MAAMQ,EAAE,GAAGT,EAAE,GAAGC,IAAI;MACpB,IAAIJ,CAAC,KAAK,CAAC,EAAE;QACX;QACAH,EAAE,CAACI,CAAC,CAAC,GAAG,CAACJ,EAAE,CAACI,CAAC,CAAC,IAAI,CAAC,IAAIU,EAAE,GAAGD,OAAO;QACnCZ,EAAE,CAACG,CAAC,CAAC,GAAG,CAACH,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,IAAIW,EAAE,GAAGF,OAAO;MACrC,CAAC,MAAM;QACLb,EAAE,CAACG,CAAC,CAAC,GAAG,CAACH,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,IAAKW,EAAE,GAAGD,OAAO,GAAI,CAAC;QACzCZ,EAAE,CAACE,CAAC,CAAC,GAAG,CAACF,EAAE,CAACE,CAAC,CAAC,IAAI,CAAC,IAAKY,EAAE,GAAGF,OAAO,GAAI,CAAC;QACzCb,EAAE,CAACI,CAAC,CAAC,GAAG,CAACJ,EAAE,CAACI,CAAC,CAAC,IAAI,CAAC,IAAKU,EAAE,GAAGD,OAAO,GAAI,CAAC;QACzCZ,EAAE,CAACG,CAAC,CAAC,GAAG,CAACH,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,IAAKW,EAAE,GAAGF,OAAO,GAAI,CAAC;MAC3C;IACF;EACF;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,SAASG,WAAWA,CAACnB,KAAa,EAAmB;EACnD,MAAMK,KAAK,GAAG,IAAIe,KAAK,CAASpB,KAAK,CAAC;EACtC,MAAMG,EAAE,GAAG,IAAIiB,KAAK,CAASpB,KAAK,CAAC;EACnC,MAAMI,EAAE,GAAG,IAAIgB,KAAK,CAASpB,KAAK,CAAC;EAEnC,KAAK,IAAIM,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,KAAK,EAAEM,CAAC,EAAE,EAAE;IAC9BD,KAAK,CAACC,CAAC,CAAC,GAAGR,cAAc,CAACQ,CAAC,EAAEN,KAAK,CAAC;IACnC,IAAIM,CAAC,KAAK,CAAC,EAAE;MACXH,EAAE,CAACG,CAAC,CAAC,GAAG,CAAC;MACTF,EAAE,CAACE,CAAC,CAAC,GAAG,CAAC;IACX,CAAC,MAAM;MACL;MACA,MAAMe,KAAK,GAAG5B,YAAY,GAAGR,IAAI,CAACE,IAAI,CAACmB,CAAC,CAAC;MACzC,MAAMgB,KAAK,GAAGhB,CAAC,GAAGtB,YAAY;MAC9BmB,EAAE,CAACG,CAAC,CAAC,GAAGe,KAAK,GAAGpC,IAAI,CAAC6B,GAAG,CAACQ,KAAK,CAAC;MAC/BlB,EAAE,CAACE,CAAC,CAAC,GAAGe,KAAK,GAAGpC,IAAI,CAAC8B,GAAG,CAACO,KAAK,CAAC;IACjC;EACF;EAEA,KAAK,IAAIC,IAAI,GAAG,CAAC,EAAEA,IAAI,GAAGnC,UAAU,EAAEmC,IAAI,EAAE,EAAE;IAC5C;IACA,KAAK,IAAIjB,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,KAAK,EAAEM,CAAC,EAAE,EAAE;MAC9BH,EAAE,CAACG,CAAC,CAAC,GAAG,CAACH,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAGhB,SAAS,CAAC;MACtCc,EAAE,CAACE,CAAC,CAAC,GAAG,CAACF,EAAE,CAACE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAGhB,SAAS,CAAC;IACxC;IACA;IACAY,QAAQ,CAACC,EAAE,EAAEC,EAAE,EAAEC,KAAK,EAAEL,KAAK,CAAC;IAC9BG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACTC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;EACX;EACA;EACA,KAAK,IAAImB,IAAI,GAAG,CAAC,EAAEA,IAAI,GAAGlC,kBAAkB,EAAEkC,IAAI,EAAE,EAAE;IACpDrB,QAAQ,CAACC,EAAE,EAAEC,EAAE,EAAEC,KAAK,EAAEL,KAAK,CAAC;IAC9BG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACTC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;EACX;;EAEA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,IAAIoB,IAAI,GAAGC,QAAQ;EACnB,IAAIC,IAAI,GAAG,CAACD,QAAQ;EACpB,IAAIE,IAAI,GAAGF,QAAQ;EACnB,IAAIG,IAAI,GAAG,CAACH,QAAQ;EACpB,KAAK,IAAInB,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,KAAK,EAAEM,CAAC,EAAE,EAAE;IAC9B,MAAMuB,CAAC,GAAG1B,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC;IACpB,MAAMwB,CAAC,GAAG1B,EAAE,CAACE,CAAC,CAAC,IAAI,CAAC;IACpB,MAAMyB,CAAC,GAAG1B,KAAK,CAACC,CAAC,CAAC,IAAI,CAAC;IACvB,IAAIuB,CAAC,GAAGE,CAAC,GAAGP,IAAI,EAAEA,IAAI,GAAGK,CAAC,GAAGE,CAAC;IAC9B,IAAIF,CAAC,GAAGE,CAAC,GAAGL,IAAI,EAAEA,IAAI,GAAGG,CAAC,GAAGE,CAAC;IAC9B,IAAID,CAAC,GAAGC,CAAC,GAAGJ,IAAI,EAAEA,IAAI,GAAGG,CAAC,GAAGC,CAAC;IAC9B,IAAID,CAAC,GAAGC,CAAC,GAAGH,IAAI,EAAEA,IAAI,GAAGE,CAAC,GAAGC,CAAC;EAChC;EACA,MAAMC,OAAO,GAAG,CAACR,IAAI,GAAGE,IAAI,IAAI,CAAC;EACjC,MAAMO,OAAO,GAAG,CAACN,IAAI,GAAGC,IAAI,IAAI,CAAC;EACjC,IAAIM,KAAK,GAAG,CAAC;EACb,KAAK,IAAI5B,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,KAAK,EAAEM,CAAC,EAAE,EAAE;IAC9B,MAAM6B,KAAK,GACTlD,IAAI,CAAC0B,KAAK,CAAC,CAACR,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,IAAI0B,OAAO,EAAE,CAAC5B,EAAE,CAACE,CAAC,CAAC,IAAI,CAAC,IAAI2B,OAAO,CAAC,IAAI5B,KAAK,CAACC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9E,IAAI6B,KAAK,GAAGD,KAAK,EAAEA,KAAK,GAAGC,KAAK;EAClC;EACA,MAAMC,KAAK,GAAGF,KAAK,GAAGrC,OAAO,GAAG,GAAG,GAAGqC,KAAK,GAAG,GAAG;EAEjD,MAAMG,OAAO,GAAG,IAAIjB,KAAK,CAAgBpB,KAAK,CAAC;EAC/C,KAAK,IAAIM,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGN,KAAK,EAAEM,CAAC,EAAE,EAAE;IAC9B+B,OAAO,CAAC/B,CAAC,CAAC,GAAG;MACXgC,EAAE,EAAE,GAAG,GAAG,CAAC,CAACnC,EAAE,CAACG,CAAC,CAAC,IAAI,CAAC,IAAI0B,OAAO,IAAII,KAAK;MAC1CG,EAAE,EAAE,GAAG,GAAG,CAAC,CAACnC,EAAE,CAACE,CAAC,CAAC,IAAI,CAAC,IAAI2B,OAAO,IAAIG,KAAK;MAC1CI,CAAC,EAAE,CAAC,IAAInC,KAAK,CAACC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG8B;IAC3B,CAAC;EACH;EACA,OAAOC,OAAO;AAChB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASI,oBAAoBA,CAACzC,KAAa,EAAmB;EACnE,IAAIA,KAAK,IAAI,CAAC,EAAE,OAAO,EAAE;EACzB,IAAIA,KAAK,KAAK,CAAC,EAAE,OAAO,CAAC;IAAEsC,EAAE,EAAE,GAAG;IAAEC,EAAE,EAAE,GAAG;IAAEC,CAAC,EAAE;EAAE,CAAC,CAAC;EACpD,IAAIxC,KAAK,KAAK,CAAC,EAAE;IACf;IACA;IACA;IACA;IACA,OAAO,CACL;MAAEsC,EAAE,EAAE,IAAI;MAAEC,EAAE,EAAE,IAAI;MAAEC,CAAC,EAAE;IAAK,CAAC,EAC/B;MAAEF,EAAE,EAAE,IAAI;MAAEC,EAAE,EAAE,IAAI;MAAEC,CAAC,EAAE;IAAK,CAAC,CAChC;EACH;EACA,IAAIxC,KAAK,KAAK,CAAC,EAAE;IACf,OAAO,CACL;MAAEsC,EAAE,EAAE,GAAG;MAAEC,EAAE,EAAE,IAAI;MAAEC,CAAC,EAAE;IAAK,CAAC,EAC9B;MAAEF,EAAE,EAAE,KAAK;MAAEC,EAAE,EAAE,IAAI;MAAEC,CAAC,EAAE;IAAI,CAAC,EAC/B;MAAEF,EAAE,EAAE,KAAK;MAAEC,EAAE,EAAE,IAAI;MAAEC,CAAC,EAAE;IAAI,CAAC,CAChC;EACH;EACA,OAAOrB,WAAW,CAACnB,KAAK,CAAC;AAC3B","ignoreList":[]}

package/lib/module/avatar-group/AvatarGroup.js

@@ -4,8 +4,9 @@ import React, { memo } from 'react';
 import { AvatarGroupBase } from "./AvatarGroupBase.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 /**
- * Native `AvatarGroup` — an overlapping, ringed stack of {@link Avatar}s with a
- * trailing `+N` overflow chip.
+ * Native `AvatarGroup` — {@link Avatar}s arranged as a horizontal facepile
+ * (`stack`), an adjacent `row`, or a 2D magnetic `cluster`, with a trailing
+ * `+N` overflow chip. See `layout` in {@link AvatarGroupProps}.
  *
  * Hover behavior is web-only; on native the `hoverCard` / `renderItemAction`
  * props are accepted for API parity but intentionally do nothing (no hover on

package/lib/module/avatar-group/AvatarGroup.js.map

@@ -1 +1 @@
-{"version":3,"names":["React","memo","AvatarGroupBase","jsx","_jsx","AvatarGroupComponent","props","AvatarGroup","displayName"],"sourceRoot":"../../../src","sources":["avatar-group/AvatarGroup.tsx"],"mappings":";;AAAA,OAAOA,KAAK,IAAIC,IAAI,QAAQ,OAAO;AAEnC,SAASC,eAAe,QAAQ,sBAAmB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAGpD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,oBAAgD,GAAIC,KAAK,IAAK;EAClE,oBAAOF,IAAA,CAACF,eAAe;IAAA,GAAKI;EAAK,CAAG,CAAC;AACvC,CAAC;AAED,OAAO,MAAMC,WAAW,gBAAGN,IAAI,CAACI,oBAAoB,CAAC;AACrDE,WAAW,CAACC,WAAW,GAAG,aAAa","ignoreList":[]}
+{"version":3,"names":["React","memo","AvatarGroupBase","jsx","_jsx","AvatarGroupComponent","props","AvatarGroup","displayName"],"sourceRoot":"../../../src","sources":["avatar-group/AvatarGroup.tsx"],"mappings":";;AAAA,OAAOA,KAAK,IAAIC,IAAI,QAAQ,OAAO;AAEnC,SAASC,eAAe,QAAQ,sBAAmB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAGpD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,oBAAgD,GAAIC,KAAK,IAAK;EAClE,oBAAOF,IAAA,CAACF,eAAe;IAAA,GAAKI;EAAK,CAAG,CAAC;AACvC,CAAC;AAED,OAAO,MAAMC,WAAW,gBAAGN,IAAI,CAACI,oBAAoB,CAAC;AACrDE,WAAW,CAACC,WAAW,GAAG,aAAa","ignoreList":[]}

package/lib/module/avatar-group/AvatarGroup.web.js

@@ -17,11 +17,11 @@ function getItemName(item) {
 }
 
 /**
- * Web `AvatarGroup`. Identical stack rendering to native via
- * {@link AvatarGroupBase}, plus an optional hover card: when `hoverCard` is
- * enabled, hovering an avatar reveals a {@link UserHoverCard} positioned beneath
- * it. The card receives the per-item `renderItemAction` slot so the app can drop
- * its SDK FollowButton inside.
+ * Web `AvatarGroup`. Identical layout rendering to native (stack / row /
+ * cluster) via {@link AvatarGroupBase}, plus an optional hover card: when
+ * `hoverCard` is enabled, hovering an avatar reveals a {@link UserHoverCard}
+ * positioned beneath it. The card receives the per-item `renderItemAction` slot
+ * so the app can drop its SDK FollowButton inside.
  */
 const AvatarGroupWebComponent = props => {
   const {

package/lib/module/avatar-group/AvatarGroupBase.js

@@ -5,6 +5,7 @@ import { Pressable, StyleSheet, Text, View } from 'react-native';
 import { Avatar } from "../avatar/index.js";
 import { useTheme } from "../theme/use-theme.js";
 import { fontSize } from "../styles/tokens.js";
+import { computeClusterLayout } from "./cluster-layout.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Ring (border) thickness around each avatar, in pixels. Matches the
  * original Mention `AvatarStack` (a single hairline-ish 1px separator). */
@@ -12,6 +13,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) {
   return item.displayName ?? item.name ?? item.username;
 }
@@ -21,12 +31,61 @@ function getItemKey(item, index) {
 
 /** Hover callbacks injected by the web fork; undefined (no-op) on native. */
 
+/**
+ * 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
+}) {
+  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 = /*#__PURE__*/_jsx(View, {
+    ref: hoverHandlers?.registerCellRef ? node => hoverHandlers.registerCellRef?.(index, node) : undefined,
+    collapsable: false,
+    style: cellStyle,
+    children: /*#__PURE__*/_jsx(Avatar, {
+      source: item.uri ?? undefined,
+      name: showInitials ? name : undefined,
+      variant: variant,
+      size: innerSize
+    })
+  });
+  if (interactive || hoverable) {
+    return /*#__PURE__*/_jsx(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,
+      children: cell
+    });
+  }
+  return /*#__PURE__*/_jsx(View, {
+    style: wrapperStyle,
+    children: cell
+  });
+}
 const AvatarGroupBaseComponent = ({
   items,
   layout = 'stack',
   size = 32,
   variant = 'thumb',
-  max = 5,
+  max,
   total,
   overlap,
   spacing,
@@ -38,6 +97,7 @@ const AvatarGroupBaseComponent = ({
   hoverHandlers
 }) => {
   const theme = useTheme();
+  const isCluster = layout === 'cluster';
   const isRow = layout === 'row';
 
   // The ring is the thin separator drawn between overlapping avatars. It
@@ -45,6 +105,7 @@ const AvatarGroupBaseComponent = ({
   // 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
   // 1px border on each side, so the negative margin absorbs both borders to
@@ -54,7 +115,7 @@ const AvatarGroupBaseComponent = ({
   const rowGap = spacing ?? Math.round(size * DEFAULT_OVERLAP_RATIO);
   // Horizontal offset applied to every avatar after the first.
   const itemMargin = isRow ? rowGap : negativeMargin;
-  const shown = useMemo(() => items.slice(0, Math.max(0, max)), [items, max]);
+  const shown = useMemo(() => items.slice(0, Math.max(0, effectiveMax)), [items, effectiveMax]);
   const realTotal = total ?? items.length;
   const overflow = Math.max(0, realTotal - shown.length);
 
@@ -84,24 +145,38 @@ const AvatarGroupBaseComponent = ({
     };
   }, [isRow, size, ring]);
   const overflowTextStyle = useMemo(() => ({
-    color: '#FFFFFF',
+    color: OVERFLOW_TEXT_COLOR,
     fontSize: Math.max(fontSize._2xs, Math.round(size * 0.36)),
     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.
   const firstHidden = items[shown.length];
   const overflowOnPress = interactive && firstHidden ? () => 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 /*#__PURE__*/_jsx(ClusterAvatarGroup, {
+      items: items,
+      size: size,
+      variant: variant,
+      max: max,
+      total: total,
+      ring: ring,
+      showInitials: showInitials,
+      onPressItem: onPressItem,
+      style: style,
+      testID: testID,
+      hoverHandlers: hoverHandlers
+    });
+  }
   return /*#__PURE__*/_jsxs(View, {
     style: [styles.row, style],
     testID: testID,
     children: [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
@@ -115,65 +190,159 @@ const AvatarGroupBaseComponent = ({
           zIndex: shown.length - index
         })
       };
-      const cell = /*#__PURE__*/_jsx(View, {
-        ref: hoverHandlers?.registerCellRef ? node => hoverHandlers.registerCellRef?.(index, node) : undefined,
-        collapsable: false,
-        style: cellStyle,
-        children: /*#__PURE__*/_jsx(Avatar, {
-          source: item.uri ?? undefined,
-          name: showInitials ? name : undefined,
-          variant: variant,
-          size: innerSize
-        })
-      });
-      if (interactive || hoverable) {
-        return /*#__PURE__*/_jsx(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,
-          children: cell
-        }, getItemKey(item, index));
-      }
-      return /*#__PURE__*/_jsx(View, {
-        style: wrapperStyle,
-        children: cell
+      return /*#__PURE__*/_jsx(AvatarGroupCell, {
+        item: item,
+        index: index,
+        innerSize: innerSize,
+        variant: variant,
+        showInitials: showInitials,
+        cellStyle: cellStyle,
+        wrapperStyle: wrapperStyle,
+        onPressItem: onPressItem,
+        hoverHandlers: hoverHandlers
       }, getItemKey(item, index));
     }), overflow > 0 && /*#__PURE__*/_jsx(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
     })]
   });
 };
+/**
+ * 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 = ({
+  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 = null;
+  if (overflow > 0 && overflowBubble) {
+    const diameter = overflowBubble.d * size;
+    overflowElement = /*#__PURE__*/_jsx(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 /*#__PURE__*/_jsxs(View, {
+    style: [{
+      width: size,
+      height: size
+    }, style],
+    testID: testID,
+    children: [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 = {
+        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 = {
+        width: diameter,
+        height: diameter,
+        borderRadius: diameter / 2,
+        borderWidth: ringWidth,
+        borderColor: ring,
+        overflow: 'hidden',
+        alignItems: 'center',
+        justifyContent: 'center'
+      };
+      return /*#__PURE__*/_jsx(AvatarGroupCell, {
+        item: item,
+        index: index,
+        innerSize: inner,
+        variant: variant,
+        showInitials: showInitials,
+        cellStyle: cellStyle,
+        wrapperStyle: wrapperStyle,
+        onPressItem: onPressItem,
+        hoverHandlers: hoverHandlers
+      }, getItemKey(item, index));
+    }), overflowElement]
+  });
+};
 function OverflowCircle({
   count,
   cellStyle,
-  marginLeft,
-  isRow,
+  wrapperStyle,
   textStyle,
   onPress
 }) {
   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 = {
-    ...(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 = /*#__PURE__*/_jsx(View, {
     style: [cellStyle, {
       backgroundColor: theme.colors.textSecondary