fix: deduplicate edit clients (#260)

Author: appflowy

cypress/e2e/account/avatar/avatar-awareness-dedupe.cy.ts

@@ -0,0 +1,151 @@
+import * as awarenessProtocol from 'y-protocols/awareness';
+
+import { TestTool } from '../../../support/page-utils';
+import { PageSelectors } from '../../../support/selectors';
+import { testLog } from '../../../support/test-helpers';
+
+import { avatarTestUtils } from './avatar-test-utils';
+
+const { generateRandomEmail, setupBeforeEach, signInAndWaitForApp, imports } = avatarTestUtils;
+const { AvatarSelectors, dbUtils } = imports;
+
+type TestWindow = Window & {
+  __APPFLOWY_AWARENESS_MAP__?: Record<string, awarenessProtocol.Awareness>;
+};
+
+const openFirstPageAndTriggerAwareness = (): void => {
+  TestTool.expandSpace(0);
+  cy.wait(1000);
+
+  PageSelectors.names().should('be.visible', { timeout: 10000 });
+  PageSelectors.names().first().then(($page) => {
+    cy.wrap($page).click({ force: true });
+  });
+
+  cy.wait(2000);
+
+  cy.get('[contenteditable="true"]').then(($editors) => {
+    if ($editors.length === 0) {
+      return;
+    }
+
+    let editorFound = false;
+
+    $editors.each((index, el) => {
+      const $el = Cypress.$(el);
+
+
+      if (!$el.attr('data-testid')?.includes('title') && !$el.hasClass('editor-title')) {
+        cy.wrap(el).click({ force: true });
+        cy.wait(500);
+        cy.wrap(el).type(' ', { force: true });
+        editorFound = true;
+        return false;
+      }
+    });
+
+    if (!editorFound) {
+      cy.wrap($editors.last()).click({ force: true });
+      cy.wait(500);
+      cy.wrap($editors.last()).type(' ', { force: true });
+    }
+  });
+
+  cy.wait(1500);
+};
+
+describe('Avatar Awareness Dedupe', () => {
+  beforeEach(() => {
+    setupBeforeEach();
+  });
+
+  it('should show one header avatar for same user across multiple awareness clients', function () {
+    const testEmail = generateRandomEmail();
+
+    signInAndWaitForApp(testEmail).then(() => {
+      testLog.info('Step 1: Open a document and trigger local awareness');
+      openFirstPageAndTriggerAwareness();
+
+      AvatarSelectors.headerAvatars().should('have.length', 1);
+
+      dbUtils.getCurrentUserUuid().then((userUuid) => {
+        expect(userUuid, 'Current user UUID should be available').to.be.a('string').and.not.be.empty;
+
+        testLog.info('Step 2: Inject two remote awareness clients for the same user UUID');
+        cy.window().then((win) => {
+          const testWindow = win as TestWindow;
+
+          expect(testWindow.__APPFLOWY_AWARENESS_MAP__, 'Awareness map test hook should be exposed').to.exist;
+          const awarenessMap = testWindow.__APPFLOWY_AWARENESS_MAP__!;
+
+          const pathMatch = win.location.pathname.match(/\/app\/[^/]+\/([^/?]+)/);
+          const currentViewId = pathMatch?.[1];
+
+          expect(currentViewId, 'Current viewId should be parsed from URL').to.be.a('string').and.not.be.empty;
+
+          const awareness = currentViewId ? awarenessMap[currentViewId] : undefined;
+          const fallbackAwareness = awareness || Object.values(awarenessMap)[0];
+
+          expect(fallbackAwareness, 'Awareness instance for active view').to.exist;
+          if (!fallbackAwareness) {
+            throw new Error('Awareness instance for active view is missing');
+          }
+
+          const targetAwareness = fallbackAwareness;
+
+          const nowSeconds = Math.floor(Date.now() / 1000);
+          const remoteClientA = 990001;
+          const remoteClientB = 990002;
+
+          const stateA = {
+            version: 1,
+            timestamp: nowSeconds,
+            user: {
+              uid: 1000001,
+              device_id: 'cypress-device-a',
+            },
+            metadata: JSON.stringify({
+              user_name: 'Same User',
+              cursor_color: '#ff6600',
+              selection_color: '#ff660040',
+              user_avatar: '',
+              user_uuid: userUuid,
+            }),
+          };
+          const stateB = {
+            version: 1,
+            timestamp: nowSeconds + 1,
+            user: {
+              uid: 2000002,
+              device_id: 'cypress-device-b',
+            },
+            metadata: JSON.stringify({
+              user_name: 'Same User',
+              cursor_color: '#ff6600',
+              selection_color: '#ff660040',
+              user_avatar: '',
+              user_uuid: userUuid,
+            }),
+          };
+
+          const states = new Map<number, Record<string, unknown>>([
+            [remoteClientA, stateA],
+            [remoteClientB, stateB],
+          ]);
+
+          // encodeAwarenessUpdate requires clocks in meta for each client id.
+          targetAwareness.meta.set(remoteClientA, { clock: 1, lastUpdated: Date.now() });
+          targetAwareness.meta.set(remoteClientB, { clock: 1, lastUpdated: Date.now() });
+
+          const update = awarenessProtocol.encodeAwarenessUpdate(targetAwareness, [remoteClientA, remoteClientB], states);
+
+          awarenessProtocol.applyAwarenessUpdate(targetAwareness, update, 'cypress');
+        });
+
+        testLog.info('Step 3: Verify header keeps one avatar for the same user');
+        cy.wait(1000);
+        AvatarSelectors.headerAvatars().should('have.length', 1);
+      });
+    });
+  });
+});

src/application/awareness/dispatch.ts

@@ -1,6 +1,6 @@
 import dayjs from 'dayjs';
 import { debounce } from 'lodash-es';
-import { useCallback, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { Editor } from 'slate';
 import { Awareness } from 'y-protocols/awareness';
 
@@ -14,6 +14,7 @@ import { convertSlateSelectionToAwareness, generateUserColors } from './utils';
 // User information parameters for awareness synchronization
 export interface UserAwarenessParams {
   uid: number;
+  user_uuid?: string;
   device_id: string;
   user_name: string;
   cursor_color: string;
@@ -35,6 +36,7 @@ export function useDispatchUserAwareness(awareness?: Awareness) {
         cursor_color: userParams.cursor_color,
         selection_color: userParams.selection_color,
         user_avatar: userParams.user_avatar || '',
+        user_uuid: userParams.user_uuid,
       };
 
       const awarenessState: AwarenessState = {
@@ -85,6 +87,7 @@ export function useDispatchCursorAwareness(awareness?: Awareness) {
         cursor_color: userParams.cursor_color,
         selection_color: userParams.selection_color,
         user_avatar: userParams.user_avatar || '',
+        user_uuid: userParams.user_uuid,
       };
 
       const awarenessState: AwarenessState = {
@@ -112,6 +115,12 @@ export function useDispatchCursorAwareness(awareness?: Awareness) {
     return debounce(syncCursor, 100);
   }, [syncCursor]);
 
+  useEffect(() => {
+    return () => {
+      debounceSyncCursor.cancel();
+    };
+  }, [debounceSyncCursor]);
+
   const dispatchCursor = useCallback(
     (userParams: UserAwarenessParams, editor?: Editor) => {
       if (!awareness || !editor) return;
@@ -169,6 +178,7 @@ export function useDispatchClearAwareness(awareness?: Awareness) {
         cursor_color: generateUserColors(currentUser?.name || '').cursor_color,
         selection_color: generateUserColors(currentUser?.name || '').selection_color,
         user_avatar: userAvatar,
+        user_uuid: currentUser?.uuid,
       }),
     });
 

src/application/awareness/selector.ts

@@ -12,6 +12,43 @@ import { convertAwarenessSelection } from './utils';
 // Re-export types for backward compatibility
 export type { AwarenessMetadata, AwarenessSelection, AwarenessState, AwarenessUser, Cursor } from './types';
 
+const getAwarenessIdentityKey = (uuid: string | undefined, uid: number, deviceId: string) => {
+  if (uuid) {
+    return `uuid:${uuid}`;
+  }
+
+  if (Number.isFinite(uid)) {
+    return `uid:${uid}`;
+  }
+
+  return `device:${deviceId}`;
+};
+
+const getNormalizedMetadata = (rawMetadata?: string): AwarenessMetadata | null => {
+  if (!rawMetadata) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(rawMetadata) as Record<string, unknown>;
+
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    return {
+      user_name: typeof parsed.user_name === 'string' ? parsed.user_name : '',
+      cursor_color: typeof parsed.cursor_color === 'string' ? parsed.cursor_color : '',
+      selection_color: typeof parsed.selection_color === 'string' ? parsed.selection_color : '',
+      user_avatar: typeof parsed.user_avatar === 'string' ? parsed.user_avatar : '',
+      user_uuid: typeof parsed.user_uuid === 'string' ? parsed.user_uuid : undefined,
+    };
+  } catch (error) {
+    Log.warn('Failed to parse awareness metadata', { error });
+    return null;
+  }
+};
+
 export function useUsersSelector(awareness?: Awareness) {
   const [users, setUsers] = useState<AwarenessUser[]>([]);
 
@@ -27,10 +64,15 @@ export function useUsersSelector(awareness?: Awareness) {
         }
 
         const uid = Number(state.user.uid);
-        const meta = JSON.parse(state.metadata || '{}') as AwarenessMetadata;
+        const meta = getNormalizedMetadata(state.metadata);
+
+        if (!meta) {
+          return;
+        }
 
         users.push({
           uid,
+          uuid: meta.user_uuid,
           name: meta.user_name,
           timestamp: state.timestamp,
           device_id: state.user.device_id,
@@ -42,7 +84,7 @@ export function useUsersSelector(awareness?: Awareness) {
       setUsers(
         uniqBy(
           users.sort((a, b) => b.timestamp - a.timestamp),
-          'uid'
+          (user) => getAwarenessIdentityKey(user.uuid, user.uid, user.device_id)
         ).filter((user) => !!user.name)
       );
     };
@@ -60,6 +102,7 @@ export function useRemoteSelectionsSelector(awareness?: Awareness) {
   const [cursors, setCursors] = useState<Cursor[]>([]);
   const editor = useSlate();
   const service = useService();
+  const localDeviceId = service?.getDeviceId();
 
   useEffect(() => {
     const renderCursors = () => {
@@ -72,11 +115,13 @@ export function useRemoteSelectionsSelector(awareness?: Awareness) {
         }
 
         const uid = Number(state.user.uid);
-        const meta = JSON.parse(state.metadata || '{}') as AwarenessMetadata;
+        const meta = getNormalizedMetadata(state.metadata);
 
-        const deviceId = service?.getDeviceId();
+        if (!meta) {
+          return;
+        }
 
-        if (deviceId === state.user.device_id) {
+        if (localDeviceId && localDeviceId === state.user.device_id) {
           return;
         }
 
@@ -85,6 +130,7 @@ export function useRemoteSelectionsSelector(awareness?: Awareness) {
 
           cursors.push({
             uid,
+            uuid: meta.user_uuid,
             name: meta.user_name,
             cursorColor: meta.cursor_color,
             selectionColor: meta.selection_color,
@@ -100,14 +146,14 @@ export function useRemoteSelectionsSelector(awareness?: Awareness) {
       setCursors(
         uniqBy(
           cursors.sort((a, b) => b.timestamp - a.timestamp),
-          'uid'
+          (cursor) => getAwarenessIdentityKey(cursor.uuid, cursor.uid, cursor.deviceId)
         )
       );
     };
 
     awareness?.on('change', renderCursors);
     return () => awareness?.off('change', renderCursors);
-  }, [awareness, service]);
+  }, [awareness, localDeviceId]);
 
   const cursorsWithBaseRange = useMemo(() => {
     if (!cursors.length || !editor || !editor.children[0]) return [];

src/application/awareness/types.ts

@@ -13,6 +13,7 @@ export interface AwarenessSelection {
 
 export interface AwarenessUser {
   uid: number;
+  uuid?: string;
   name: string;
   timestamp: number;
   device_id: string;
@@ -25,6 +26,7 @@ export interface AwarenessMetadata {
   cursor_color: string;
   selection_color: string;
   user_avatar: string;
+  user_uuid?: string;
 }
 
 export interface AwarenessState {
@@ -40,6 +42,7 @@ export interface AwarenessState {
 
 export interface Cursor {
   uid: number;
+  uuid?: string;
   deviceId: string;
   name: string;
   cursorColor: string;

src/application/services/js-services/device-id.ts

@@ -0,0 +1,37 @@
+import { nanoid } from 'nanoid';
+
+const DEVICE_ID_STORAGE_KEY = 'x-device-id';
+
+let memoizedDeviceId: string | undefined;
+
+/**
+ * Returns a stable device ID for the current browser profile.
+ * Falls back to an in-memory ID if localStorage is unavailable.
+ */
+export function getOrCreateDeviceId(): string {
+  if (memoizedDeviceId) {
+    return memoizedDeviceId;
+  }
+
+  if (typeof window !== 'undefined') {
+    try {
+      const stored = window.localStorage.getItem(DEVICE_ID_STORAGE_KEY);
+
+      if (stored) {
+        memoizedDeviceId = stored;
+        return stored;
+      }
+
+      const created = nanoid(8);
+
+      window.localStorage.setItem(DEVICE_ID_STORAGE_KEY, created);
+      memoizedDeviceId = created;
+      return created;
+    } catch {
+      // Fall back to memory-only device id below.
+    }
+  }
+
+  memoizedDeviceId = nanoid(8);
+  return memoizedDeviceId;
+}