feat(editor): dedupe connected collaborators by identity

The presence avatars were keyed by Yjs awareness clientId, so the same
person showed up once per connection: every extra tab/device, and every
lingering pre-timeout socket left behind by a reconnect (amplified by the
refocus re-sync), rendered the same circle again.

Collapse awareness clients sharing an identity (HF username, falling back to
avatar URL then clientId) into a single avatar, with a "xN" badge + tooltip
when a person has multiple live sessions.

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend/src/components/ConnectedUsers.tsx

@@ -22,11 +22,31 @@ import { useEffect, useState } from "react";
 import type { HocuspocusProvider } from "@hocuspocus/provider";
 import { Tooltip } from "./Tooltip";
 
-interface AwarenessUser {
+/**
+ * One unique person currently editing, after collapsing every awareness
+ * client that shares the same identity. `count` is how many live
+ * connections (tabs / devices / lingering pre-timeout sockets) that person
+ * has - surfaced as a small badge instead of repeating the same avatar.
+ */
+interface ConnectedUser {
+  key: string;
   clientId: number;
   name: string;
   color: string;
   avatarUrl?: string;
+  count: number;
+}
+
+/**
+ * Stable identity key for deduplication. The HF username (`name`) is unique
+ * per account, so it's the primary key; we fall back to the avatar URL and
+ * finally the clientId so anonymous / malformed states still render once.
+ */
+function identityKey(name: string, avatarUrl?: string, clientId?: number): string {
+  const n = name.trim().toLowerCase();
+  if (n) return `name:${n}`;
+  if (avatarUrl) return `avatar:${avatarUrl}`;
+  return `client:${clientId ?? "?"}`;
 }
 
 interface Props {
@@ -37,7 +57,7 @@ interface Props {
 const MAX_VISIBLE = 4;
 
 export function ConnectedUsers({ providerRef }: Props) {
-  const [users, setUsers] = useState<AwarenessUser[]>([]);
+  const [users, setUsers] = useState<ConnectedUser[]>([]);
 
   useEffect(() => {
     let cleanup: (() => void) | null = null;
@@ -49,12 +69,14 @@ export function ConnectedUsers({ providerRef }: Props) {
 
       const sync = () => {
         const localClientId = awareness.clientID;
-        const arr: AwarenessUser[] = [];
+
+        // First pass: one entry per awareness client (raw connections).
+        const raw: Omit<ConnectedUser, "key" | "count">[] = [];
         awareness.getStates().forEach((state: any, clientId: number) => {
           if (clientId === localClientId) return;
           const user = state?.user;
           if (!user || !user.name) return;
-          arr.push({
+          raw.push({
             clientId,
             name: String(user.name),
             color: String(user.color || "#888"),
@@ -63,8 +85,23 @@ export function ConnectedUsers({ providerRef }: Props) {
         });
         // Stable order: by clientId so the avatars don't dance around
         // every time someone moves their cursor and emits an update.
-        arr.sort((a, b) => a.clientId - b.clientId);
-        setUsers(arr);
+        raw.sort((a, b) => a.clientId - b.clientId);
+
+        // Second pass: collapse same-identity clients into one avatar.
+        // The same person opening two tabs - or a stale pre-timeout socket
+        // lingering next to a fresh reconnect - used to render the exact
+        // same circle N times. Now we show it once with a "xN" badge.
+        const byKey = new Map<string, ConnectedUser>();
+        for (const u of raw) {
+          const key = identityKey(u.name, u.avatarUrl, u.clientId);
+          const existing = byKey.get(key);
+          if (existing) {
+            existing.count += 1;
+          } else {
+            byKey.set(key, { ...u, key, count: 1 });
+          }
+        }
+        setUsers([...byKey.values()]);
       };
 
       sync();
@@ -101,7 +138,10 @@ export function ConnectedUsers({ providerRef }: Props) {
   return (
     <div className="connected-users" aria-label={totalLabel}>
       {visible.map((u) => (
-        <Tooltip key={u.clientId} title={u.name}>
+        <Tooltip
+          key={u.key}
+          title={u.count > 1 ? `${u.name} (${u.count} open sessions)` : u.name}
+        >
           <span
             className="connected-users__avatar"
             style={{ borderColor: u.color }}
@@ -116,6 +156,11 @@ export function ConnectedUsers({ providerRef }: Props) {
                 {u.name.slice(0, 1).toUpperCase()}
               </span>
             )}
+            {u.count > 1 && (
+              <span className="connected-users__count" aria-hidden="true">
+                {u.count}
+              </span>
+            )}
           </span>
         </Tooltip>
       ))}

frontend/src/styles/components/_connected-users.css

@@ -21,7 +21,8 @@
   width: 24px;
   height: 24px;
   border-radius: 50%;
-  overflow: hidden;
+  /* No overflow:hidden here: the circular clip lives on the img/initials so
+     the count badge can sit on top of (and slightly outside) the avatar. */
   border: 2px solid var(--border-color);
   background: var(--surface-bg);
   margin-left: -6px;
@@ -33,6 +34,11 @@
 }
 .connected-users__avatar:hover {
   transform: translateY(-1px) scale(1.08);
+  z-index: 3;
+}
+/* Keep badged avatars above their right-hand neighbour so the count
+   (which sits on the right edge, where avatars overlap) stays visible. */
+.connected-users__avatar:has(> .connected-users__count) {
   z-index: 2;
 }
 
@@ -41,6 +47,7 @@
   height: 100%;
   object-fit: cover;
   display: block;
+  border-radius: 50%;
 }
 
 .connected-users__initials {
@@ -54,6 +61,28 @@
   color: #fff;
   text-transform: uppercase;
   line-height: 1;
+  border-radius: 50%;
+}
+
+.connected-users__count {
+  position: absolute;
+  bottom: -3px;
+  right: -4px;
+  min-width: 14px;
+  height: 14px;
+  padding: 0 3px;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 7px;
+  background: var(--primary-color);
+  color: var(--on-primary, #fff);
+  font-size: 9px;
+  font-weight: 700;
+  line-height: 1;
+  border: 1.5px solid var(--surface-bg);
+  font-variant-numeric: tabular-nums;
 }
 
 .connected-users__more {