@rgby/collab-core 1.0.1

package/src/extensions/collaboration-cursor.ts

@@ -0,0 +1,188 @@
+import { Extension } from '@tiptap/core'
+import type { DecorationAttrs } from '@tiptap/pm/view'
+import { defaultSelectionBuilder, yCursorPlugin } from '@tiptap/y-tiptap'
+
+type CollaborationCaretStorage = {
+    users: { clientId: number;[key: string]: any }[]
+}
+
+export interface CollaborationCaretOptions {
+    /**
+     * The Hocuspocus provider instance. This can also be a TiptapCloudProvider instance.
+     * @type {HocuspocusProvider | TiptapCloudProvider}
+     * @example new HocuspocusProvider()
+     */
+    provider: any
+
+    /**
+     * The user details object – feel free to add properties to this object as needed
+     * @example { name: 'John Doe', color: '#305500' }
+     */
+    user: Record<string, any>
+
+    /**
+     * A function that returns a DOM element for the cursor.
+     * @param user The user details object
+     * @example
+     * render: user => {
+     *  const cursor = document.createElement('span')
+     *  cursor.classList.add('collaboration-carets__caret')
+     *  cursor.setAttribute('style', `border-color: ${user.color}`)
+     *
+     *  const label = document.createElement('div')
+     *  label.classList.add('collaboration-carets__label')
+     *  label.setAttribute('style', `background-color: ${user.color}`)
+     *  label.insertBefore(document.createTextNode(user.name), null)
+     *
+     *  cursor.insertBefore(label, null)
+     *  return cursor
+     * }
+     */
+    render(user: Record<string, any>): HTMLElement
+
+    /**
+     * A function that returns a ProseMirror DecorationAttrs object for the selection.
+     * @param user The user details object
+     * @example
+     * selectionRender: user => {
+     * return {
+     *  nodeName: 'span',
+     *  class: 'collaboration-carets__selection',
+     *  style: `background-color: ${user.color}`,
+     *  'data-user': user.name,
+     * }
+     */
+    selectionRender(user: Record<string, any>): DecorationAttrs
+
+    /**
+     * @deprecated The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+     */
+    onUpdate: (users: { clientId: number;[key: string]: any }[]) => null
+}
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        collaborationCaret: {
+            /**
+             * Update details of the current user
+             * @example editor.commands.updateUser({ name: 'John Doe', color: '#305500' })
+             */
+            updateUser: (attributes: Record<string, any>) => ReturnType
+            /**
+             * Update details of the current user
+             *
+             * @deprecated The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret
+             */
+            user: (attributes: Record<string, any>) => ReturnType
+        }
+    }
+
+    interface Storage {
+        collaborationCaret: CollaborationCaretStorage
+    }
+}
+
+const awarenessStatesToArray = (states: Map<number, Record<string, any>>) => {
+    return Array.from(states.entries()).map(([key, value]) => {
+        return {
+            clientId: key,
+            ...value.user,
+        }
+    })
+}
+
+const defaultOnUpdate = () => null
+
+/**
+ * This extension allows you to add collaboration carets to your editor.
+ * @see https://tiptap.dev/api/extensions/collaboration-caret
+ */
+export const CollaborationCursor = Extension.create<CollaborationCaretOptions, CollaborationCaretStorage>({
+    name: 'collaborationCursor', // Kept generic name to match expectation
+
+    priority: 999,
+
+    addOptions() {
+        return {
+            provider: null,
+            user: {
+                name: null,
+                color: null,
+            },
+            render: user => {
+                const cursor = document.createElement('span')
+
+                cursor.classList.add('collaboration-cursor__caret')
+                cursor.setAttribute('style', `border-color: ${user.color}`)
+
+                const label = document.createElement('div')
+
+                label.classList.add('collaboration-cursor__label')
+                label.setAttribute('style', `background-color: ${user.color}`)
+                label.insertBefore(document.createTextNode(user.name), null)
+                cursor.insertBefore(label, null)
+
+                return cursor
+            },
+            selectionRender: defaultSelectionBuilder,
+            onUpdate: defaultOnUpdate,
+        }
+    },
+
+    onCreate() {
+        if (this.options.onUpdate !== defaultOnUpdate) {
+            console.warn(
+                '[tiptap warn]: DEPRECATED: The "onUpdate" option is deprecated. Please use `editor.storage.collaborationCaret.users` instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',
+            )
+        }
+        if (!this.options.provider) {
+            throw new Error('The "provider" option is required for the CollaborationCaret extension')
+        }
+    },
+
+    addStorage() {
+        return {
+            users: [],
+        }
+    },
+
+    addCommands() {
+        return {
+            updateUser: (attributes: Record<string, any>) => () => {
+                this.options.provider.awareness.setLocalStateField('user', attributes)
+                return true
+            },
+            user:
+                (attributes: Record<string, any>) =>
+                    ({ editor }) => {
+                        console.warn(
+                            '[tiptap warn]: DEPRECATED: The "user" command is deprecated. Please use "updateUser" instead. Read more: https://tiptap.dev/api/extensions/collaboration-caret',
+                        )
+
+                        return editor.commands.updateUser(attributes)
+                    },
+        }
+    },
+
+    addProseMirrorPlugins() {
+        return [
+            yCursorPlugin(
+                (() => {
+                    this.options.provider.awareness.setLocalStateField('user', this.options.user)
+
+                    this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)
+
+                    this.options.provider.awareness.on('update', () => {
+                        this.storage.users = awarenessStatesToArray(this.options.provider.awareness.states)
+                    })
+
+                    return this.options.provider.awareness
+                })(),
+                {
+                    cursorBuilder: this.options.render,
+                    selectionBuilder: this.options.selectionRender,
+                },
+            ),
+        ]
+    },
+})

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './collab-provider.js'
+
+export * from './upload-queue.js'
+export * from './services/sw-manager.js'
+export { Collaboration } from '@tiptap/extension-collaboration'
+export { CollaborationCursor } from './extensions/collaboration-cursor.js'

package/src/services/sw-manager.ts

@@ -0,0 +1,255 @@
+/**
+ * Service Worker Manager
+ * Handles SW registration, updates, and cache management
+ */
+
+export interface ServiceWorkerManagerOptions {
+    scriptUrl?: string;
+    scope?: string;
+    onUpdate?: (registration: ServiceWorkerRegistration) => void;
+    onReady?: (registration: ServiceWorkerRegistration) => void;
+    onError?: (error: Error) => void;
+}
+
+export class ServiceWorkerManager {
+    private registration: ServiceWorkerRegistration | null = null;
+    private options: ServiceWorkerManagerOptions;
+    private updateCheckInterval: ReturnType<typeof setInterval> | null = null;
+
+    constructor(options: ServiceWorkerManagerOptions = {}) {
+        this.options = {
+            scriptUrl: options.scriptUrl || '/sw.js',
+            scope: options.scope || '/',
+            ...options
+        };
+    }
+
+    /**
+     * Register the Service Worker
+     */
+    async register(): Promise<ServiceWorkerRegistration | null> {
+        // Check if Service Worker is supported
+        if (!('serviceWorker' in navigator)) {
+            console.warn('[SW Manager] Service Workers not supported in this browser');
+            return null;
+        }
+
+        // Check if we're in a secure context (HTTPS or localhost)
+        if (!window.isSecureContext) {
+            console.warn('[SW Manager] Service Workers require a secure context (HTTPS)');
+            return null;
+        }
+
+        try {
+            console.log('[SW Manager] Registering Service Worker...');
+            const registration = await navigator.serviceWorker.register(
+                this.options.scriptUrl!,
+                { scope: this.options.scope }
+            );
+
+            this.registration = registration;
+
+            // Handle updates
+            registration.addEventListener('updatefound', () => {
+                const newWorker = registration.installing;
+                if (!newWorker) return;
+
+                newWorker.addEventListener('statechange', () => {
+                    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
+                        console.log('[SW Manager] New version available');
+                        if (this.options.onUpdate) {
+                            this.options.onUpdate(registration);
+                        }
+                    }
+                });
+            });
+
+            // Check if SW is already active
+            if (registration.active) {
+                console.log('[SW Manager] Service Worker active');
+                if (this.options.onReady) {
+                    this.options.onReady(registration);
+                }
+            }
+
+            // Periodically check for updates (every 1 hour)
+            this.updateCheckInterval = setInterval(() => {
+                registration.update().catch((error) => {
+                    console.error('[SW Manager] Update check failed:', error);
+                });
+            }, 60 * 60 * 1000);
+
+            console.log('[SW Manager] Service Worker registered successfully');
+            return registration;
+        } catch (error) {
+            console.error('[SW Manager] Registration failed:', error);
+            if (this.options.onError) {
+                this.options.onError(error as Error);
+            }
+            return null;
+        }
+    }
+
+    /**
+     * Unregister the Service Worker
+     */
+    async unregister(): Promise<boolean> {
+        if (!this.registration) {
+            return false;
+        }
+
+        try {
+            const success = await this.registration.unregister();
+            if (success) {
+                console.log('[SW Manager] Service Worker unregistered');
+                this.registration = null;
+                if (this.updateCheckInterval) {
+                    clearInterval(this.updateCheckInterval);
+                    this.updateCheckInterval = null;
+                }
+            }
+            return success;
+        } catch (error) {
+            console.error('[SW Manager] Unregistration failed:', error);
+            return false;
+        }
+    }
+
+    /**
+     * Update the Service Worker
+     */
+    async update(): Promise<void> {
+        if (!this.registration) {
+            throw new Error('No Service Worker registered');
+        }
+
+        try {
+            await this.registration.update();
+            console.log('[SW Manager] Update check complete');
+        } catch (error) {
+            console.error('[SW Manager] Update failed:', error);
+            throw error;
+        }
+    }
+
+    /**
+     * Skip waiting and activate new Service Worker immediately
+     */
+    async skipWaiting(): Promise<void> {
+        if (!this.registration || !this.registration.waiting) {
+            return;
+        }
+
+        // Send message to waiting SW to skip waiting
+        this.registration.waiting.postMessage({ type: 'SKIP_WAITING' });
+
+        // Wait for the new SW to take control
+        return new Promise<void>((resolve) => {
+            navigator.serviceWorker.addEventListener('controllerchange', () => {
+                console.log('[SW Manager] New Service Worker activated');
+                resolve();
+            });
+        });
+    }
+
+    /**
+     * Clear all caches
+     */
+    async clearCache(): Promise<boolean> {
+        if (!this.registration || !this.registration.active) {
+            return false;
+        }
+
+        return new Promise((resolve) => {
+            const messageChannel = new MessageChannel();
+            messageChannel.port1.onmessage = (event) => {
+                resolve(event.data.success || false);
+            };
+
+            this.registration!.active!.postMessage(
+                { type: 'CLEAR_CACHE' },
+                [messageChannel.port2]
+            );
+        });
+    }
+
+    /**
+     * Get current cache size
+     */
+    async getCacheSize(): Promise<number> {
+        if (!this.registration || !this.registration.active) {
+            return 0;
+        }
+
+        return new Promise((resolve) => {
+            const messageChannel = new MessageChannel();
+            messageChannel.port1.onmessage = (event) => {
+                resolve(event.data.size || 0);
+            };
+
+            this.registration!.active!.postMessage(
+                { type: 'GET_CACHE_SIZE' },
+                [messageChannel.port2]
+            );
+        });
+    }
+
+    /**
+     * Check if Service Worker is active
+     */
+    isActive(): boolean {
+        return this.registration !== null && this.registration.active !== null;
+    }
+
+    /**
+     * Get Service Worker status
+     */
+    getStatus(): 'unsupported' | 'inactive' | 'installing' | 'waiting' | 'active' {
+        if (!('serviceWorker' in navigator)) {
+            return 'unsupported';
+        }
+
+        if (!this.registration) {
+            return 'inactive';
+        }
+
+        if (this.registration.installing) {
+            return 'installing';
+        }
+
+        if (this.registration.waiting) {
+            return 'waiting';
+        }
+
+        if (this.registration.active) {
+            return 'active';
+        }
+
+        return 'inactive';
+    }
+
+    /**
+     * Get the registration
+     */
+    getRegistration(): ServiceWorkerRegistration | null {
+        return this.registration;
+    }
+}
+
+/**
+ * Create and register a Service Worker manager instance
+ */
+export async function registerServiceWorker(
+    options?: ServiceWorkerManagerOptions
+): Promise<ServiceWorkerManager> {
+    const manager = new ServiceWorkerManager(options);
+    await manager.register();
+    return manager;
+}
+
+/**
+ * Check if Service Workers are supported
+ */
+export function isServiceWorkerSupported(): boolean {
+    return 'serviceWorker' in navigator && window.isSecureContext;
+}

package/src/test-deps.ts

@@ -0,0 +1,34 @@
+// Re-export common dependencies to ensure singleton instances
+import * as Y from "yjs";
+
+// Export Yjs parts
+export { Y };
+export * from "yjs";
+
+// Export Awareness for y-protocols/awareness mapping
+export * from "y-protocols/awareness";
+
+// Export Sync and Auth protocols (manually to avoid collisions)
+export {
+    messageYjsSyncStep1,
+    messageYjsSyncStep2,
+    messageYjsUpdate,
+    writeSyncStep1,
+    writeSyncStep2,
+    writeUpdate,
+    readSyncStep1,
+    readSyncStep2,
+} from "y-protocols/sync";
+export * from "y-protocols/auth";
+
+// Export Tiptap parts
+export { Editor, Extension } from "@tiptap/core";
+export { default as Document } from "@tiptap/extension-document";
+export { default as Paragraph } from "@tiptap/extension-paragraph";
+export { default as Text } from "@tiptap/extension-text";
+export { default as StarterKit } from "@tiptap/starter-kit";
+export { default as Collaboration } from "@tiptap/extension-collaboration";
+export { CollaborationCursor } from "./extensions/collaboration-cursor.js";
+
+// Export Hocuspocus Provider
+export * from "@hocuspocus/provider";