Реалізація Cursor Presence (курсори користувачів) на сайті

Реалізація Cursor Presence (курсори користувачів) на сайті

Cursor presence — відображення курсорів та виділень інших учасників у реальному часі. Візуально просто; складність прихована у трьох речах: ефективній передачі координат, інтерполяції рухів та корректному маппінгу позицій при зміні контенту.

Модель даних presence

Кожен клієнт трансліює свій стан: позицію курсора, активний елемент, можливо — виділення тексту. Мінімальна структура:

interface UserPresence {
  userId:    string;
  name:      string;
  color:     string;
  cursor: {
    x:       number;
    y:       number;
  } | null;
  selection?: {
    anchor:  number;
    head:    number;
  };
  activeElement?: string;
  lastSeen:  number;
}

Передача через WebSocket: throttle обов'язковий

Mousemove генерує 50–100 подій/сек. Без throttle, 10 користувачів = тисячі повідомлень/сек на сервер. Розумна межа — 30 fps (33ms).

import { throttle } from 'lodash-es';

const sendCursor = throttle((x: number, y: number) => {
  socket.emit('cursor:move', { x, y });
}, 33);

document.addEventListener('mousemove', (e) => {
  sendCursor(e.clientX, e.clientY);
});

document.addEventListener('mouseleave', () => {
  socket.emit('cursor:leave');
});

Сервер (Socket.IO) — broadcast у кімнату, окрім відправника:

socket.on('cursor:move', (data: { x: number; y: number }) => {
  socket.to(roomId).emit('cursor:update', {
    userId: socket.data.userId,
    ...data,
  });
});

socket.on('cursor:leave', () => {
  socket.to(roomId).emit('cursor:remove', {
    userId: socket.data.userId,
  });
});

socket.on('disconnect', () => {
  socket.to(roomId).emit('cursor:remove', {
    userId: socket.data.userId,
  });
});

Рендеринг: інтерполяція

Прямое оновлення позиції по кожній події — дергаючіся курсори. CSS transition: transform 0.1s linear — вносить задержку в іншому напрямку. Правильно — linear interpolation (lerp) в requestAnimationFrame:

interface RemoteCursor {
  userId:    string;
  name:      string;
  color:     string;
  current:   { x: number; y: number };
  target:    { x: number; y: number };
  el:        HTMLElement;
}

const cursors = new Map<string, RemoteCursor>();

function lerp(a: number, b: number, t: number) {
  return a + (b - a) * t;
}

function animateCursors() {
  cursors.forEach((cursor) => {
    cursor.current.x = lerp(cursor.current.x, cursor.target.x, 0.35);
    cursor.current.y = lerp(cursor.current.y, cursor.target.y, 0.35);
    cursor.el.style.transform =
      `translate(${cursor.current.x}px, ${cursor.current.y}px)`;
  });
  requestAnimationFrame(animateCursors);
}

animateCursors();

// При оновленні — лише змінюємо target
socket.on('cursor:update', ({ userId, x, y, name, color }) => {
  if (!cursors.has(userId)) {
    const el = createCursorElement(userId, name, color);
    document.body.appendChild(el);
    cursors.set(userId, {
      userId, name, color,
      current: { x, y },
      target:  { x, y },
      el,
    });
  } else {
    cursors.get(userId)!.target = { x, y };
  }
});

HTML-елемент курсора

function createCursorElement(userId: string, name: string, color: string): HTMLElement {
  const wrapper = document.createElement('div');
  wrapper.style.cssText = `
    position: fixed;
    top: 0; left: 0;
    pointer-events: none;
    z-index: 9999;
    will-change: transform;
  `;
  wrapper.innerHTML = `
    <svg width="16" height="20" viewBox="0 0 16 20" fill="none">
      <path d="M0 0L0 16L4 12L7 18L9 17L6 11L11 11Z"
            fill="${color}" stroke="white" stroke-width="1"/>
    </svg>
    <span style="
      background: ${color};
      color: white;
      font-size: 11px;
      padding: 2px 6px;
      border-radius: 4px;
      white-space: nowrap;
      margin-left: 12px;
      margin-top: -4px;
      display: inline-block;
      font-family: system-ui;
    ">${name}</span>
  `;
  return wrapper;
}

Presence через Yjs Awareness

Якщо проект вже використовує Yjs, Awareness — вбудований механізм presence:

import { WebsocketProvider } from 'y-websocket';

const provider = new WebsocketProvider(wsUrl, roomName, ydoc);

// Встановлюємо свій стан
provider.awareness.setLocalState({
  user: {
    id:    currentUser.id,
    name:  currentUser.name,
    color: generateColor(currentUser.id),
  },
  cursor: null,
});

// Оновлення позиції курсора
document.addEventListener('mousemove', throttle((e) => {
  provider.awareness.setLocalStateField('cursor', {
    x: e.clientX,
    y: e.clientY,
  });
}, 33));

// Підписка на зміни
provider.awareness.on('change', ({ added, updated, removed }) => {
  const states = provider.awareness.getStates();

  [...added, ...updated].forEach((clientId) => {
    if (clientId === provider.awareness.clientID) return;
    const state = states.get(clientId);
    if (state?.cursor) {
      updateCursor(clientId, state.user, state.cursor);
    }
  });

  removed.forEach((clientId) => {
    removeCursor(clientId);
  });
});

Координати: viewport проти document

Якщо сторінка скроллиться, viewport-координати (clientX/Y) недостатньо — чужі курсори зсунуться. Потрібні document-relative координати:

document.addEventListener('mousemove', throttle((e) => {
  provider.awareness.setLocalStateField('cursor', {
    x: e.clientX + window.scrollX,
    y: e.clientY + window.scrollY,
  });
}, 33));

// При рендеринзу — переводимо назад
function getCursorViewportPos(docX: number, docY: number) {
  return {
    x: docX - window.scrollX,
    y: docY - window.scrollY,
  };
}

Курсори у текстових редакторах

Позиція в тексті — не координата, а смішення символу. Маппінг на екранну позицію через Range API:

function getCaretCoordinates(offset: number): { x: number; y: number } | null {
  const range = document.createRange();
  const editorEl = document.getElementById('editor')!;
  let charCount = 0;

  function findNode(node: Node): boolean {
    if (node.nodeType === Node.TEXT_NODE) {
      const len = node.textContent!.length;
      if (charCount + len >= offset) {
        range.setStart(node, offset - charCount);
        range.collapse(true);
        return true;
      }
      charCount += len;
    } else {
      for (const child of node.childNodes) {
        if (findNode(child)) return true;
      }
    }
    return false;
  }

  if (!findNode(editorEl)) return null;

  const rect = range.getBoundingClientRect();
  return { x: rect.left, y: rect.top };
}

Для ProseMirror та CodeMirror — готові утиліти (view.coordsAtPos()), не потрібно вручну.

TTL та cleanup

Якщо користувач закрив вкладку без явного disconnect — його курсор залишиться. Рішення — heartbeat + TTL:

const CURSOR_TTL = 5000; // 5 сек без оновлень

const lastSeen = new Map<string, number>();

socket.on('cursor:update', ({ userId, ...pos }) => {
  lastSeen.set(userId, Date.now());
  updateCursor(userId, pos);
});

setInterval(() => {
  const now = Date.now();
  lastSeen.forEach((ts, userId) => {
    if (now - ts > CURSOR_TTL) {
      removeCursor(userId);
      lastSeen.delete(userId);
    }
  });
}, 1000);

Реалізація cursor presence з нуля — 1–2 дні. Якщо вже використовуєте Yjs або Socket.IO, через awareness/broadcast — половина дня.