@object-ui/collaboration 2.0.0

package/dist/LiveCursors.js

@@ -0,0 +1,100 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React, { useMemo } from 'react';
+const cursorStyles = {
+    container: {
+        position: 'absolute',
+        inset: 0,
+        pointerEvents: 'none',
+        overflow: 'hidden',
+        zIndex: 9999,
+    },
+    cursor: {
+        position: 'absolute',
+        pointerEvents: 'none',
+        transition: 'transform 120ms ease-out, opacity 300ms ease',
+        willChange: 'transform, opacity',
+    },
+    label: {
+        position: 'absolute',
+        left: '16px',
+        top: '16px',
+        fontSize: '11px',
+        fontWeight: 500,
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        color: '#fff',
+        padding: '1px 6px',
+        borderRadius: '3px',
+        whiteSpace: 'nowrap',
+        lineHeight: '18px',
+    },
+    avatar: {
+        position: 'absolute',
+        left: '18px',
+        top: '-4px',
+        width: '18px',
+        height: '18px',
+        borderRadius: '50%',
+        border: '2px solid #fff',
+        objectFit: 'cover',
+    },
+};
+function CursorSvg({ color, size }) {
+    return React.createElement('svg', {
+        width: size,
+        height: size,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+        xmlns: 'http://www.w3.org/2000/svg',
+        style: { display: 'block' },
+    }, React.createElement('path', {
+        d: 'M5.65376 12.3673H5.46026L5.31717 12.4976L0.500002 16.8829L0.500002 1.19841L11.7841 12.3673H5.65376Z',
+        fill: color,
+        stroke: '#fff',
+        strokeWidth: '1',
+    }));
+}
+/**
+ * Live cursors component displaying other users' cursor positions.
+ *
+ * Renders absolutely-positioned cursor SVGs with smooth CSS transitions,
+ * user name labels, and fade-out for idle users.
+ */
+export function LiveCursors({ users, containerRef: _containerRef, showNames = true, showAvatars = false, cursorSize = 20, fadeIdle = true, className, }) {
+    const visibleUsers = useMemo(() => users.filter(u => u.cursor), [users]);
+    return React.createElement('div', {
+        style: cursorStyles.container,
+        className,
+        'aria-hidden': 'true',
+    }, visibleUsers.map(user => {
+        const { cursor } = user;
+        if (!cursor)
+            return null;
+        const opacity = fadeIdle
+            ? user.status === 'active' ? 1 : user.status === 'idle' ? 0.5 : 0.2
+            : 1;
+        return React.createElement('div', {
+            key: user.userId,
+            style: {
+                ...cursorStyles.cursor,
+                transform: `translate(${cursor.x}px, ${cursor.y}px)`,
+                opacity,
+            },
+            'data-user-id': user.userId,
+        }, React.createElement(CursorSvg, { color: user.color, size: cursorSize }), showAvatars && user.avatar && React.createElement('img', {
+            src: user.avatar,
+            alt: user.userName,
+            style: cursorStyles.avatar,
+        }), showNames && React.createElement('span', {
+            style: {
+                ...cursorStyles.label,
+                backgroundColor: user.color,
+            },
+        }, user.userName));
+    }));
+}

package/dist/PresenceAvatars.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import type { PresenceUser } from './usePresence';
+export interface PresenceAvatarsProps {
+    /** Present users */
+    users: PresenceUser[];
+    /** Max avatars to show before "+N" */
+    maxVisible?: number;
+    /** Avatar size */
+    size?: 'sm' | 'md' | 'lg';
+    /** Show status indicators */
+    showStatus?: boolean;
+    /** Additional className */
+    className?: string;
+}
+/**
+ * Avatar stack component showing active users with overflow indicator.
+ *
+ * Displays user avatars (or initials) in an overlapping stack,
+ * with optional status indicators and a "+N" overflow badge.
+ */
+export declare function PresenceAvatars({ users, maxVisible, size, showStatus, className, }: PresenceAvatarsProps): React.ReactElement;
+//# sourceMappingURL=PresenceAvatars.d.ts.map

package/dist/PresenceAvatars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PresenceAvatars.d.ts","sourceRoot":"","sources":["../src/PresenceAvatars.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAkB,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,oBAAoB;IACnC,oBAAoB;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,6BAA6B;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,UAAc,EACd,IAAW,EACX,UAAiB,EACjB,SAAS,GACV,EAAE,oBAAoB,GAAG,KAAK,CAAC,YAAY,CA6F3C"}

package/dist/PresenceAvatars.js

@@ -0,0 +1,113 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React, { useMemo } from 'react';
+const sizeMap = {
+    sm: 24,
+    md: 32,
+    lg: 40,
+};
+const statusColors = {
+    active: '#22c55e',
+    idle: '#f59e0b',
+    away: '#94a3b8',
+};
+function getInitials(name) {
+    return name
+        .split(' ')
+        .map(part => part[0])
+        .join('')
+        .toUpperCase()
+        .slice(0, 2);
+}
+/**
+ * Avatar stack component showing active users with overflow indicator.
+ *
+ * Displays user avatars (or initials) in an overlapping stack,
+ * with optional status indicators and a "+N" overflow badge.
+ */
+export function PresenceAvatars({ users, maxVisible = 5, size = 'md', showStatus = true, className, }) {
+    const px = sizeMap[size];
+    const overlapOffset = Math.round(px * 0.3);
+    const fontSize = Math.round(px * 0.35);
+    const statusDotSize = Math.max(8, Math.round(px * 0.28));
+    const visible = useMemo(() => users.slice(0, maxVisible), [users, maxVisible]);
+    const overflowCount = Math.max(0, users.length - maxVisible);
+    const containerStyle = {
+        display: 'inline-flex',
+        alignItems: 'center',
+        flexDirection: 'row-reverse',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    };
+    const avatarBaseStyle = {
+        width: `${px}px`,
+        height: `${px}px`,
+        borderRadius: '50%',
+        border: '2px solid #fff',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        fontSize: `${fontSize}px`,
+        fontWeight: 600,
+        color: '#fff',
+        position: 'relative',
+        flexShrink: 0,
+        overflow: 'hidden',
+        boxSizing: 'border-box',
+    };
+    const overflowStyle = {
+        ...avatarBaseStyle,
+        backgroundColor: '#e2e8f0',
+        color: '#475569',
+        marginLeft: `-${overlapOffset}px`,
+    };
+    const statusDotStyle = {
+        position: 'absolute',
+        bottom: '-1px',
+        right: '-1px',
+        width: `${statusDotSize}px`,
+        height: `${statusDotSize}px`,
+        borderRadius: '50%',
+        border: '2px solid #fff',
+        boxSizing: 'border-box',
+    };
+    // Render in reverse order so the first user appears on top (z-index via DOM order with row-reverse)
+    const reversedVisible = useMemo(() => [...visible].reverse(), [visible]);
+    return React.createElement('div', {
+        style: containerStyle,
+        className,
+        role: 'group',
+        'aria-label': `${users.length} user${users.length !== 1 ? 's' : ''} present`,
+    }, 
+    // Overflow badge (rendered first because of row-reverse)
+    overflowCount > 0 && React.createElement('div', {
+        key: 'overflow',
+        style: overflowStyle,
+        title: `${overflowCount} more user${overflowCount !== 1 ? 's' : ''}`,
+    }, `+${overflowCount}`), 
+    // Avatars
+    reversedVisible.map((user, idx) => React.createElement('div', {
+        key: user.userId,
+        style: {
+            ...avatarBaseStyle,
+            backgroundColor: user.color,
+            marginLeft: idx > 0 || overflowCount > 0 ? `-${overlapOffset}px` : '0',
+        },
+        title: `${user.userName} (${user.status})`,
+    }, user.avatar
+        ? React.createElement('img', {
+            src: user.avatar,
+            alt: user.userName,
+            style: { width: '100%', height: '100%', objectFit: 'cover' },
+        })
+        : getInitials(user.userName), showStatus && React.createElement('span', {
+        style: {
+            ...statusDotStyle,
+            backgroundColor: statusColors[user.status],
+        },
+    }))));
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * @object-ui/collaboration
+ *
+ * Real-time collaboration for Object UI providing:
+ * - useRealtimeSubscription hook for WebSocket data subscriptions
+ * - usePresence hook for live cursor and presence tracking
+ * - useConflictResolution hook for version history and conflict management
+ * - CommentThread component for threaded comments with @mentions
+ * - LiveCursors component for displaying remote user cursors
+ * - PresenceAvatars component for showing active user avatars
+ *
+ * @packageDocumentation
+ */
+export { useRealtimeSubscription, type RealtimeConfig, type ConnectionState, type RealtimeMessage, type RealtimeResult, } from './useRealtimeSubscription';
+export { usePresence, createPresenceUpdater, type PresenceUser, type PresenceConfig, type PresenceResult, } from './usePresence';
+export { useConflictResolution, type VersionEntry, type ConflictInfo, type ConflictResolutionResult, } from './useConflictResolution';
+export { CommentThread, type Comment, type CommentThreadProps, } from './CommentThread';
+export { LiveCursors, type LiveCursorsProps, } from './LiveCursors';
+export { PresenceAvatars, type PresenceAvatarsProps, } from './PresenceAvatars';
+export type { CollaborationPresence, CollaborationOperation, CollaborationConfig, } from '@object-ui/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * @object-ui/collaboration
+ *
+ * Real-time collaboration for Object UI providing:
+ * - useRealtimeSubscription hook for WebSocket data subscriptions
+ * - usePresence hook for live cursor and presence tracking
+ * - useConflictResolution hook for version history and conflict management
+ * - CommentThread component for threaded comments with @mentions
+ * - LiveCursors component for displaying remote user cursors
+ * - PresenceAvatars component for showing active user avatars
+ *
+ * @packageDocumentation
+ */
+export { useRealtimeSubscription, } from './useRealtimeSubscription';
+export { usePresence, createPresenceUpdater, } from './usePresence';
+export { useConflictResolution, } from './useConflictResolution';
+export { CommentThread, } from './CommentThread';
+export { LiveCursors, } from './LiveCursors';
+export { PresenceAvatars, } from './PresenceAvatars';

package/dist/useConflictResolution.d.ts

@@ -0,0 +1,72 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { CollaborationConfig } from '@object-ui/types';
+export interface VersionEntry {
+    id: string;
+    version: number;
+    timestamp: string;
+    userId: string;
+    userName?: string;
+    changes: Record<string, {
+        before: unknown;
+        after: unknown;
+    }>;
+    message?: string;
+}
+export interface ConflictInfo {
+    id: string;
+    field: string;
+    localValue: unknown;
+    remoteValue: unknown;
+    baseValue: unknown;
+    localTimestamp: string;
+    remoteTimestamp: string;
+    remoteUserId: string;
+}
+export interface ConflictResolutionResult {
+    /** Version history entries */
+    versions: VersionEntry[];
+    /** Current version number */
+    currentVersion: number;
+    /** Pending conflicts that need resolution */
+    conflicts: ConflictInfo[];
+    /** Whether there are unresolved conflicts */
+    hasConflicts: boolean;
+    /** Record a new version */
+    recordVersion: (changes: Record<string, {
+        before: unknown;
+        after: unknown;
+    }>, message?: string) => void;
+    /** Resolve a conflict */
+    resolveConflict: (conflictId: string, resolution: 'local' | 'remote' | 'merge', mergedValue?: unknown) => void;
+    /** Resolve all conflicts with a strategy */
+    resolveAllConflicts: (strategy: 'local' | 'remote') => void;
+    /** Revert to a previous version */
+    revertToVersion: (versionId: string) => Record<string, unknown> | null;
+    /** Compare two versions */
+    compareVersions: (versionA: string, versionB: string) => Record<string, {
+        before: unknown;
+        after: unknown;
+    }> | null;
+    /** Add a conflict */
+    addConflict: (conflict: Omit<ConflictInfo, 'id'>) => void;
+    /** Clear version history */
+    clearHistory: () => void;
+}
+/**
+ * Hook for conflict resolution with version history.
+ *
+ * Manages a local version history and conflict queue. Supports
+ * last-write-wins, manual merge, and server-wins resolution strategies.
+ *
+ * @param userId - Current user ID
+ * @param userName - Current user display name
+ * @param _config - Optional collaboration config (for future server-side integration)
+ */
+export declare function useConflictResolution(userId: string, userName?: string, _config?: CollaborationConfig): ConflictResolutionResult;
+//# sourceMappingURL=useConflictResolution.d.ts.map

package/dist/useConflictResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConflictResolution.d.ts","sourceRoot":"","sources":["../src/useConflictResolution.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,8BAA8B;IAC9B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,6BAA6B;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,YAAY,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACxG,yBAAyB;IACzB,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/G,4CAA4C;IAC5C,mBAAmB,EAAE,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAC;IAC5D,mCAAmC;IACnC,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvE,2BAA2B;IAC3B,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACpH,qBAAqB;IACrB,WAAW,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC;IAC1D,4BAA4B;IAC5B,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,wBAAwB,CAoN1B"}

package/dist/useConflictResolution.js

@@ -0,0 +1,211 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useState, useCallback, useMemo } from 'react';
+let conflictCounter = 0;
+function generateConflictId() {
+    conflictCounter += 1;
+    return `conflict-${Date.now()}-${conflictCounter}`;
+}
+let versionIdCounter = 0;
+function generateVersionId() {
+    versionIdCounter += 1;
+    return `ver-${Date.now()}-${versionIdCounter}`;
+}
+/**
+ * Hook for conflict resolution with version history.
+ *
+ * Manages a local version history and conflict queue. Supports
+ * last-write-wins, manual merge, and server-wins resolution strategies.
+ *
+ * @param userId - Current user ID
+ * @param userName - Current user display name
+ * @param _config - Optional collaboration config (for future server-side integration)
+ */
+export function useConflictResolution(userId, userName, _config) {
+    const [versions, setVersions] = useState([]);
+    const [conflicts, setConflicts] = useState([]);
+    const currentVersion = useMemo(() => {
+        if (versions.length === 0)
+            return 0;
+        return versions[versions.length - 1].version;
+    }, [versions]);
+    const hasConflicts = conflicts.length > 0;
+    const recordVersion = useCallback((changes, message) => {
+        setVersions(prev => {
+            const nextVersion = prev.length === 0 ? 1 : prev[prev.length - 1].version + 1;
+            const entry = {
+                id: generateVersionId(),
+                version: nextVersion,
+                timestamp: new Date().toISOString(),
+                userId,
+                userName,
+                changes,
+                message,
+            };
+            return [...prev, entry];
+        });
+    }, [userId, userName]);
+    const resolveConflict = useCallback((conflictId, resolution, mergedValue) => {
+        setConflicts(prev => {
+            const conflict = prev.find(c => c.id === conflictId);
+            if (!conflict)
+                return prev;
+            let resolvedValue;
+            switch (resolution) {
+                case 'local':
+                    resolvedValue = conflict.localValue;
+                    break;
+                case 'remote':
+                    resolvedValue = conflict.remoteValue;
+                    break;
+                case 'merge':
+                    resolvedValue = mergedValue ?? conflict.localValue;
+                    break;
+            }
+            // Record the resolution as a version entry
+            setVersions(vPrev => {
+                const nextVersion = vPrev.length === 0 ? 1 : vPrev[vPrev.length - 1].version + 1;
+                const entry = {
+                    id: generateVersionId(),
+                    version: nextVersion,
+                    timestamp: new Date().toISOString(),
+                    userId,
+                    userName,
+                    changes: {
+                        [conflict.field]: { before: conflict.baseValue, after: resolvedValue },
+                    },
+                    message: `Resolved conflict on "${conflict.field}" using ${resolution} strategy`,
+                };
+                return [...vPrev, entry];
+            });
+            return prev.filter(c => c.id !== conflictId);
+        });
+    }, [userId, userName]);
+    const resolveAllConflicts = useCallback((strategy) => {
+        setConflicts(prev => {
+            if (prev.length === 0)
+                return prev;
+            const allChanges = {};
+            for (const conflict of prev) {
+                allChanges[conflict.field] = {
+                    before: conflict.baseValue,
+                    after: strategy === 'local' ? conflict.localValue : conflict.remoteValue,
+                };
+            }
+            setVersions(vPrev => {
+                const nextVersion = vPrev.length === 0 ? 1 : vPrev[vPrev.length - 1].version + 1;
+                const entry = {
+                    id: generateVersionId(),
+                    version: nextVersion,
+                    timestamp: new Date().toISOString(),
+                    userId,
+                    userName,
+                    changes: allChanges,
+                    message: `Resolved all conflicts using ${strategy} strategy`,
+                };
+                return [...vPrev, entry];
+            });
+            return [];
+        });
+    }, [userId, userName]);
+    const revertToVersion = useCallback((versionId) => {
+        const targetIdx = versions.findIndex(v => v.id === versionId);
+        if (targetIdx === -1)
+            return null;
+        // Build the state at the target version by replaying changes
+        const state = {};
+        for (let i = 0; i <= targetIdx; i++) {
+            const entry = versions[i];
+            for (const [field, change] of Object.entries(entry.changes)) {
+                state[field] = change.after;
+            }
+        }
+        // Record the revert as a new version
+        const revertChanges = {};
+        const currentState = {};
+        for (const entry of versions) {
+            for (const [field, change] of Object.entries(entry.changes)) {
+                currentState[field] = change.after;
+            }
+        }
+        for (const [field, value] of Object.entries(state)) {
+            if (currentState[field] !== value) {
+                revertChanges[field] = { before: currentState[field], after: value };
+            }
+        }
+        if (Object.keys(revertChanges).length > 0) {
+            setVersions(prev => {
+                const nextVersion = prev.length === 0 ? 1 : prev[prev.length - 1].version + 1;
+                const entry = {
+                    id: generateVersionId(),
+                    version: nextVersion,
+                    timestamp: new Date().toISOString(),
+                    userId,
+                    userName,
+                    changes: revertChanges,
+                    message: `Reverted to version ${versions[targetIdx].version}`,
+                };
+                return [...prev, entry];
+            });
+        }
+        return state;
+    }, [versions, userId, userName]);
+    const compareVersions = useCallback((versionA, versionB) => {
+        const idxA = versions.findIndex(v => v.id === versionA);
+        const idxB = versions.findIndex(v => v.id === versionB);
+        if (idxA === -1 || idxB === -1)
+            return null;
+        const [startIdx, endIdx] = idxA < idxB ? [idxA, idxB] : [idxB, idxA];
+        // Build state at each version
+        const buildState = (upTo) => {
+            const state = {};
+            for (let i = 0; i <= upTo; i++) {
+                for (const [field, change] of Object.entries(versions[i].changes)) {
+                    state[field] = change.after;
+                }
+            }
+            return state;
+        };
+        const stateA = buildState(startIdx);
+        const stateB = buildState(endIdx);
+        const allFields = new Set([...Object.keys(stateA), ...Object.keys(stateB)]);
+        const diff = {};
+        for (const field of allFields) {
+            const valA = stateA[field];
+            const valB = stateB[field];
+            if (valA !== valB) {
+                diff[field] = { before: valA, after: valB };
+            }
+        }
+        return diff;
+    }, [versions]);
+    const addConflict = useCallback((conflict) => {
+        const newConflict = {
+            ...conflict,
+            id: generateConflictId(),
+        };
+        setConflicts(prev => [...prev, newConflict]);
+    }, []);
+    const clearHistory = useCallback(() => {
+        setVersions([]);
+        setConflicts([]);
+    }, []);
+    return {
+        versions,
+        currentVersion,
+        conflicts,
+        hasConflicts,
+        recordVersion,
+        resolveConflict,
+        resolveAllConflicts,
+        revertToVersion,
+        compareVersions,
+        addConflict,
+        clearHistory,
+    };
+}

package/dist/usePresence.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export interface PresenceUser {
+    userId: string;
+    userName: string;
+    avatar?: string;
+    color: string;
+    cursor?: {
+        x: number;
+        y: number;
+        elementId?: string;
+    };
+    selection?: {
+        start: number;
+        end: number;
+        elementId?: string;
+    };
+    status: 'active' | 'idle' | 'away';
+    lastActivity: string;
+}
+export interface PresenceConfig {
+    /** Current user info */
+    user: {
+        id: string;
+        name: string;
+        avatar?: string;
+    };
+    /** Update throttle in ms (default: 50) */
+    throttleMs?: number;
+    /** Idle timeout in ms (default: 60000) */
+    idleTimeout?: number;
+    /** Away timeout in ms (default: 300000) */
+    awayTimeout?: number;
+}
+export interface PresenceResult {
+    /** All users present (excluding current user) */
+    users: PresenceUser[];
+    /** Total user count (including current) */
+    userCount: number;
+    /** Update current user's cursor position */
+    updateCursor: (position: {
+        x: number;
+        y: number;
+        elementId?: string;
+    }) => void;
+    /** Update current user's selection */
+    updateSelection: (selection: {
+        start: number;
+        end: number;
+        elementId?: string;
+    }) => void;
+    /** Current user's presence data */
+    currentUser: PresenceUser;
+}
+/**
+ * Hook for live cursors and presence tracking.
+ *
+ * Tracks cursor position with throttled updates, detects idle/away status
+ * through activity monitoring, and manages a set of remote users.
+ *
+ * @param sendPresence - Callback to broadcast presence updates to other users
+ * @param config - Presence configuration
+ */
+export declare function usePresence(sendPresence: (user: PresenceUser) => void, config: PresenceConfig): PresenceResult;
+/**
+ * Update remote user presence. Call this when receiving presence data
+ * from other users via the realtime channel.
+ *
+ * @returns A function to update or remove a remote user from the presence set.
+ */
+export declare function createPresenceUpdater(): {
+    updateUser: (user: PresenceUser) => void;
+    removeUser: (userId: string) => void;
+    getUsers: () => PresenceUser[];
+    onUsersChange: (callback: (users: Map<string, PresenceUser>) => void) => () => void;
+};
+//# sourceMappingURL=usePresence.d.ts.map

package/dist/usePresence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePresence.d.ts","sourceRoot":"","sources":["../src/usePresence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,YAAY,EAAE,CAAC,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC/E,sCAAsC;IACtC,eAAe,EAAE,CAAC,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACzF,mCAAmC;IACnC,WAAW,EAAE,YAAY,CAAC;CAC3B;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,EAC1C,MAAM,EAAE,cAAc,GACrB,cAAc,CAmIhB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI;IACvC,UAAU,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,EAAE,MAAM,YAAY,EAAE,CAAC;IAC/B,aAAa,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACrF,CAyBA"}