Add unified useAwareness() hook with simplified API

Implement a new unified useAwareness() hook that consolidates
useRemoteUsers(), useLiveRemoteUsers(), and useUserCursors() into
a single flexible API.

Key changes:
- Remove excludeLocal option - hook always excludes local user
- Support cached mode for smooth avatar transitions (60s TTL)
- Support map format for efficient Monaco cursor CSS generation
- Add comprehensive test coverage (26 tests)

API:
- useAwareness() - live remote users (for cursors)
- useAwareness({ cached: true }) - cached remote users (for avatars)
- useAwareness({ format: 'map' }) - Map format (for Monaco CSS)

Legacy hooks remain available but are marked as deprecated.

Migrate components to unified useAwareness() API

Migrate all collaborative editor components to use the new
simplified useAwareness() hook and update test mocks.

Component migrations:
- ActiveCollaborators: useRemoteUsers() → useAwareness({ cached: true })
- Cursors: useUserCursors() → useAwareness({ format: 'map' })
- CollaborationWidget: useAwarenessUsers() → useAwareness({ cached: true })
- RemoteCursor: useRemoteUsers() → useAwareness()

Test updates:
- Update mocks to use useAwareness instead of legacy hooks

UX improvements:
- CollaborationWidget now shows "You + N others" for clarity
- RemoteCursor bug fix: cursors now disappear immediately on disconnect

Optimize remote cursor rendering to prevent jumpy movement

Fixes browser-specific issue where remote cursors appeared jumpy when
viewport updates were frequent (during panning/zooming). The problem
was render storms interrupting CSS transitions.

Changes:
- Add position rounding to reduce micro-pixel updates
- Replace left/top positioning with CSS transform for better GPU acceleration
- Wrap RemoteCursor in React.memo with custom comparison to skip re-renders
  when position changes are <1px

This prevents frequent viewport updates from recreating cursor elements
and interrupting their CSS transitions.

Author: stuartc

assets/js/collaborative-editor/components/ActiveCollaborators.tsx

@@ -1,5 +1,5 @@
 import { cn } from '../../utils/cn';
-import { useRemoteUsers } from '../hooks/useAwareness';
+import { useAwareness } from '../hooks/useAwareness';
 import { getAvatarInitials } from '../utils/avatar';
 
 import { Tooltip } from './Tooltip';
@@ -15,7 +15,7 @@ interface ActiveCollaboratorsProps {
 }
 
 export function ActiveCollaborators({ className }: ActiveCollaboratorsProps) {
-  const remoteUsers = useRemoteUsers();
+  const remoteUsers = useAwareness({ cached: true });
 
   if (remoteUsers.length === 0) {
     return null;

assets/js/collaborative-editor/components/CollaborationWidget.tsx

@@ -5,14 +5,15 @@
 
 import { useSocket } from '../../react/contexts/SocketProvider';
 import { cn } from '../../utils/cn';
-import { useAwarenessUsers } from '../hooks/useAwareness';
+import { useAwareness } from '../hooks/useAwareness';
 import { useSession } from '../hooks/useSession';
 
 export function CollaborationWidget() {
   const { isConnected: socketConnected, connectionError } = useSocket();
   const { isConnected: yjsConnected, isSynced } = useSession();
 
-  const users = useAwarenessUsers();
+  // Get remote users only (local user is always excluded)
+  const remoteUsers = useAwareness({ cached: true });
 
   const getStatusColor = () => {
     if (socketConnected && yjsConnected && isSynced) return 'bg-green-500';
@@ -40,19 +41,20 @@ export function CollaborationWidget() {
         </div>
 
         {/* Separator */}
-        {users.length > 0 && <div className="w-px h-3 bg-gray-300" />}
+        {remoteUsers.length > 0 && <div className="w-px h-3 bg-gray-300" />}
 
         {/* Online users */}
-        {users.length > 0 && (
+        {remoteUsers.length > 0 && (
           <div className="flex items-center gap-1">
             <span className="text-gray-500">
-              {users.length} user{users.length !== 1 ? 's' : ''}:
+              You + {remoteUsers.length} other
+              {remoteUsers.length !== 1 ? 's' : ''}:
             </span>
             <div className="flex gap-1">
-              {users.slice(0, 3).map(user => (
+              {remoteUsers.slice(0, 3).map(user => (
                 <div
                   key={user.clientId}
-                  className="flex items-center gap-1 px-2 py-0.5 
+                  className="flex items-center gap-1 px-2 py-0.5
                              bg-gray-50 rounded-full"
                   title={`${user.user.name} (Client ${user.clientId})`}
                 >
@@ -65,9 +67,9 @@ export function CollaborationWidget() {
                   </span>
                 </div>
               ))}
-              {users.length > 3 && (
+              {remoteUsers.length > 3 && (
                 <span className="text-gray-400 px-1">
-                  +{users.length - 3} more
+                  +{remoteUsers.length - 3} more
                 </span>
               )}
             </div>

assets/js/collaborative-editor/components/Cursors.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useMemo } from 'react';
 
-import { useUserCursors, useRemoteUsers } from '../hooks/useAwareness';
+import { useAwareness } from '../hooks/useAwareness';
 
 function BaseStyles() {
   const baseStyles = `
@@ -46,16 +46,14 @@ function BaseStyles() {
  * Cursors component using awareness hooks for better performance and maintainability
  *
  * Key improvements:
- * - Uses useUserCursors() hook with memoized Map for efficient lookups
- * - Uses useRemoteUsers() for selection data (referentially stable)
+ * - Uses useAwareness() hook with Map format for efficient clientId lookups
+ * - Returns referentially stable data that only changes when users change
  * - Eliminates manual awareness state management and reduces re-renders
  */
 export function Cursors() {
   // Get cursor data as a Map for efficient clientId lookups
-  const cursorsMap = useUserCursors();
-
-  // Get remote users for selection data
-  const remoteUsers = useRemoteUsers();
+  // Note: Uses live users only (not cached), always excludes local user
+  const cursorsMap = useAwareness({ format: 'map' });
 
   // Dynamic user-specific cursor styles - now using Map entries
   const userStyles = useMemo(() => {
@@ -127,7 +125,7 @@ export function Cursors() {
     return () => {
       editorElement?.removeEventListener('scroll', checkCursorPositions);
     };
-  }, [remoteUsers.length]); // Only re-run when remote users change
+  }, [cursorsMap.size]); // Only re-run when live users change
 
   return (
     <>

assets/js/collaborative-editor/components/diagram/RemoteCursor.tsx

@@ -1,8 +1,8 @@
 import { useViewport } from '@xyflow/react';
-import { useMemo } from 'react';
+import { memo, useMemo } from 'react';
 
 import { cn } from '../../../utils/cn';
-import { useRemoteUsers } from '../../hooks/useAwareness';
+import { useAwareness } from '../../hooks/useAwareness';
 
 import { denormalizePointerPosition } from './normalizePointer';
 
@@ -15,7 +15,7 @@ interface RemoteCursor {
 }
 
 export function RemoteCursors() {
-  const remoteUsers = useRemoteUsers();
+  const remoteUsers = useAwareness();
   const { x: tx, y: ty, zoom: tzoom } = useViewport();
 
   const cursors = useMemo<RemoteCursor[]>(() => {
@@ -30,12 +30,14 @@ export function RemoteCursors() {
           [tx, ty, tzoom]
         );
 
+        // Round to nearest pixel to reduce micro-updates
+        // that trigger unnecessary re-renders
         return {
           clientId: user.clientId,
           name: user.user.name,
           color: user.user.color,
-          x: screenPos.x,
-          y: screenPos.y,
+          x: Math.round(screenPos.x),
+          y: Math.round(screenPos.y),
         };
       });
   }, [remoteUsers, tx, ty, tzoom]);
@@ -66,42 +68,57 @@ interface RemoteCursorProps {
   y: number;
 }
 
-function RemoteCursor({ name, color, x, y }: RemoteCursorProps) {
-  return (
-    <div
-      className="absolute transition-all duration-100 ease-out"
-      style={{
-        left: `${x}px`,
-        top: `${y}px`,
-        transform: 'translate(-2px, -2px)', // small shift to align pointer well
-      }}
-    >
-      {/* Cursor pointer (SVG arrow) */}
-      <svg
-        width="24"
-        height="24"
-        viewBox="0 0 24 24"
-        fill="none"
-        xmlns="http://www.w3.org/2000/svg"
-        className="drop-shadow-md"
-      >
-        <path
-          d="M 4.580503,0.60395675 A 2,2 0 0 1 6.850503,0.18395675 V 0.18395675 L 22.780503,7.4039568 A 2,2 0 0 1 23.980503,9.5239568 A 2.26,2.26 0 0 1 22.180503,11.523957 L 16.600503,12.653957 L 15.470503,18.233957 A 2.26,2.26 0 0 1 13.470503,20.033957 H 13.220503 A 2,2 0 0 1 11.350503,18.833957 L 4.160503,2.8739568 A 2,2 0 0 1 4.580503,0.60395675 Z"
-          fill={color}
-          stroke="white"
-          strokeWidth="1.5"
-        />
-      </svg>
-      {/* User name label */}
+// Memoize RemoteCursor to prevent re-renders when position hasn't changed
+// significantly. This prevents CSS transitions from being interrupted by
+// frequent viewport updates.
+const RemoteCursor = memo(
+  function RemoteCursor({ name, color, x, y }: RemoteCursorProps) {
+    return (
       <div
-        className={cn(
-          'absolute left-7 top-0 whitespace-nowrap rounded px-2 py-1',
-          'text-xs font-medium text-white shadow-md'
-        )}
-        style={{ backgroundColor: color }}
+        className="absolute transition-all duration-100 ease-out"
+        style={{
+          // Use transform for better GPU acceleration and smoother transitions
+          // Translate by (x-2, y-2) to align pointer well
+          transform: `translate(${x - 2}px, ${y - 2}px)`,
+        }}
       >
-        {name}
+        {/* Cursor pointer (SVG arrow) */}
+        <svg
+          width="24"
+          height="24"
+          viewBox="0 0 24 24"
+          fill="none"
+          xmlns="http://www.w3.org/2000/svg"
+          className="drop-shadow-md"
+        >
+          <path
+            d="M 4.580503,0.60395675 A 2,2 0 0 1 6.850503,0.18395675 V 0.18395675 L 22.780503,7.4039568 A 2,2 0 0 1 23.980503,9.5239568 A 2.26,2.26 0 0 1 22.180503,11.523957 L 16.600503,12.653957 L 15.470503,18.233957 A 2.26,2.26 0 0 1 13.470503,20.033957 H 13.220503 A 2,2 0 0 1 11.350503,18.833957 L 4.160503,2.8739568 A 2,2 0 0 1 4.580503,0.60395675 Z"
+            fill={color}
+            stroke="white"
+            strokeWidth="1.5"
+          />
+        </svg>
+        {/* User name label */}
+        <div
+          className={cn(
+            'absolute left-7 top-0 whitespace-nowrap rounded px-2 py-1',
+            'text-xs font-medium text-white shadow-md'
+          )}
+          style={{ backgroundColor: color }}
+        >
+          {name}
+        </div>
       </div>
-    </div>
-  );
-}
+    );
+  },
+  // Custom comparison: only re-render if position changed by >1px
+  // This prevents render storms from micro viewport changes
+  (prev, next) => {
+    return (
+      prev.name === next.name &&
+      prev.color === next.color &&
+      Math.abs(prev.x - next.x) < 1 &&
+      Math.abs(prev.y - next.y) < 1
+    );
+  }
+);