@rgby/collab-core 1.0.1

package/src/collab-provider.ts

@@ -0,0 +1,1871 @@
+
+import { HocuspocusProvider, HocuspocusProviderWebsocket } from "@hocuspocus/provider";
+import * as Yjs from "yjs";
+import { IndexeddbPersistence } from "y-indexeddb";
+import { UploadQueueManager, type PendingUpload } from "./upload-queue.js";
+
+// Re-export Yjs as Y for compatibility
+export const Y = Yjs;
+
+type HocuspocusProviderConfiguration = ConstructorParameters<typeof HocuspocusProvider>[0];
+type HocuspocusProviderWebsocketConfiguration = ConstructorParameters<typeof HocuspocusProviderWebsocket>[0];
+
+// ----------------------------------------------------------------------
+// Interfaces & Types
+// ----------------------------------------------------------------------
+
+export interface AuthClient {
+    getSession: () => Promise<{ session: { token: string } | null } | null>;
+    subscribe: (callback: (session: { session: { token: string } | null } | null) => void) => () => void;
+}
+
+// ----------------------------------------------------------------------
+// Storage Abstraction
+// ----------------------------------------------------------------------
+
+export interface StorageAdapter {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+
+export class LocalStorageAdapter implements StorageAdapter {
+    getItem(key: string): string | null {
+        try {
+            return localStorage.getItem(key);
+        } catch {
+            return null;
+        }
+    }
+
+    setItem(key: string, value: string): void {
+        try {
+            localStorage.setItem(key, value);
+        } catch {
+            // Ignore errors (quota exceeded, etc.)
+        }
+    }
+
+    removeItem(key: string): void {
+        try {
+            localStorage.removeItem(key);
+        } catch {
+            // Ignore errors
+        }
+    }
+}
+
+export class SessionStorageAdapter implements StorageAdapter {
+    getItem(key: string): string | null {
+        try {
+            return sessionStorage.getItem(key);
+        } catch {
+            return null;
+        }
+    }
+
+    setItem(key: string, value: string): void {
+        try {
+            sessionStorage.setItem(key, value);
+        } catch {
+            // Ignore errors
+        }
+    }
+
+    removeItem(key: string): void {
+        try {
+            sessionStorage.removeItem(key);
+        } catch {
+            // Ignore errors
+        }
+    }
+}
+
+export class MemoryStorageAdapter implements StorageAdapter {
+    private store: Map<string, string> = new Map();
+
+    getItem(key: string): string | null {
+        return this.store.get(key) ?? null;
+    }
+
+    setItem(key: string, value: string): void {
+        this.store.set(key, value);
+    }
+
+    removeItem(key: string): void {
+        this.store.delete(key);
+    }
+}
+
+// ----------------------------------------------------------------------
+// AuthManager
+// ----------------------------------------------------------------------
+
+export interface SessionData {
+    token: string;
+    user: { id: string; name: string; email: string; image?: string };
+    expiresAt: number; // Unix timestamp (seconds)
+}
+
+export interface AuthManagerOptions {
+    baseUrl: string;
+    storage?: StorageAdapter;
+    storageKey?: string;
+    autoRefresh?: boolean;
+    refreshBuffer?: number; // Seconds before expiry to refresh
+}
+
+export class AuthManager {
+    private baseUrl: string;
+    private storage: StorageAdapter;
+    private storageKey: string;
+    private autoRefresh: boolean;
+    private refreshBuffer: number;
+    private session: SessionData | null = null;
+    private subscribers: Set<(session: SessionData | null) => void> = new Set();
+    private refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+    constructor(options: AuthManagerOptions) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.storage = options.storage ?? new LocalStorageAdapter();
+        this.storageKey = options.storageKey ?? 'collab_session';
+        this.autoRefresh = options.autoRefresh ?? true;
+        this.refreshBuffer = options.refreshBuffer ?? 3600; // 1 hour default
+
+        // Restore session from storage
+        this.restoreSession();
+    }
+
+    private async restoreSession(): Promise<void> {
+        try {
+            const stored = await this.storage.getItem(this.storageKey);
+            if (stored) {
+                const session = JSON.parse(stored) as SessionData;
+
+                // Check if session is still valid
+                const now = Math.floor(Date.now() / 1000);
+                if (session.expiresAt > now) {
+                    this.session = session;
+                    this.scheduleRefresh();
+                    this.notifySubscribers();
+                } else {
+                    // Session expired, clear it
+                    await this.storage.removeItem(this.storageKey);
+                }
+            }
+        } catch (e) {
+            console.error('[AuthManager] Failed to restore session:', e);
+        }
+    }
+
+    private async persistSession(session: SessionData | null): Promise<void> {
+        try {
+            if (session) {
+                await this.storage.setItem(this.storageKey, JSON.stringify(session));
+            } else {
+                await this.storage.removeItem(this.storageKey);
+            }
+        } catch (e) {
+            console.error('[AuthManager] Failed to persist session:', e);
+        }
+    }
+
+    private scheduleRefresh(): void {
+        if (!this.autoRefresh || !this.session) return;
+
+        // Clear existing timer
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+        }
+
+        const now = Math.floor(Date.now() / 1000);
+        const timeUntilRefresh = (this.session.expiresAt - this.refreshBuffer) - now;
+
+        if (timeUntilRefresh > 0) {
+            this.refreshTimer = setTimeout(() => {
+                this.refreshSession();
+            }, timeUntilRefresh * 1000);
+        }
+    }
+
+    private async refreshSession(): Promise<void> {
+        if (!this.session) return;
+
+        try {
+            const res = await fetch(`${this.baseUrl}/api/auth/session`, {
+                headers: {
+                    'Authorization': `Bearer ${this.session.token}`
+                }
+            });
+
+            if (res.ok) {
+                const data = await res.json();
+                if (data.session?.token && data.user) {
+                    const newSession: SessionData = {
+                        token: data.session.token,
+                        user: {
+                            id: data.user.id,
+                            name: data.user.name,
+                            email: data.user.email,
+                            image: data.user.image
+                        },
+                        expiresAt: data.session.expiresAt
+                    };
+                    this.session = newSession;
+                    await this.persistSession(newSession);
+                    this.scheduleRefresh();
+                    this.notifySubscribers();
+                }
+            }
+        } catch (e) {
+            console.error('[AuthManager] Failed to refresh session:', e);
+        }
+    }
+
+    private notifySubscribers(): void {
+        this.subscribers.forEach(callback => callback(this.session));
+    }
+
+    async login(email: string, password: string): Promise<SessionData> {
+        const res = await fetch(`${this.baseUrl}/api/auth/sign-in/email`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Origin': this.baseUrl
+            },
+            body: JSON.stringify({ email, password })
+        });
+
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ message: res.statusText }));
+            throw new Error(error.message || 'Login failed');
+        }
+
+        const data = await res.json();
+
+        // Better Auth can return token in different formats
+        const token = data.token || data.session?.token;
+        const expiresAt = data.session?.expiresAt || data.expiresAt;
+
+        if (!token || !data.user) {
+            throw new Error('Invalid response from server');
+        }
+
+        const session: SessionData = {
+            token,
+            user: {
+                id: data.user.id,
+                name: data.user.name,
+                email: data.user.email,
+                image: data.user.image
+            },
+            expiresAt: expiresAt || (Math.floor(Date.now() / 1000) + 7200) // 2 hours default
+        };
+
+        this.session = session;
+        await this.persistSession(session);
+        this.scheduleRefresh();
+        this.notifySubscribers();
+
+        return session;
+    }
+
+    async signup(email: string, password: string, name: string): Promise<SessionData> {
+        const res = await fetch(`${this.baseUrl}/api/auth/sign-up/email`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Origin': this.baseUrl
+            },
+            body: JSON.stringify({ email, password, name })
+        });
+
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ message: res.statusText }));
+            throw new Error(error.message || 'Signup failed');
+        }
+
+        const data = await res.json();
+
+        // Better Auth can return token in different formats
+        const token = data.token || data.session?.token;
+        const expiresAt = data.session?.expiresAt || data.expiresAt;
+
+        if (!token || !data.user) {
+            throw new Error('Invalid response from server');
+        }
+
+        const session: SessionData = {
+            token,
+            user: {
+                id: data.user.id,
+                name: data.user.name,
+                email: data.user.email,
+                image: data.user.image
+            },
+            expiresAt: expiresAt || (Math.floor(Date.now() / 1000) + 7200) // 2 hours default
+        };
+
+        this.session = session;
+        await this.persistSession(session);
+        this.scheduleRefresh();
+        this.notifySubscribers();
+
+        return session;
+    }
+
+    async logout(): Promise<void> {
+        if (!this.session) return;
+
+        try {
+            await fetch(`${this.baseUrl}/api/auth/sign-out`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.session.token}`
+                }
+            });
+        } catch (e) {
+            console.error('[AuthManager] Logout request failed:', e);
+        }
+
+        this.session = null;
+        await this.persistSession(null);
+
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+
+        this.notifySubscribers();
+    }
+
+    getSession(): SessionData | null {
+        return this.session;
+    }
+
+    getToken(): string | null {
+        return this.session?.token ?? null;
+    }
+
+    subscribe(callback: (session: SessionData | null) => void): () => void {
+        this.subscribers.add(callback);
+        return () => this.subscribers.delete(callback);
+    }
+
+    // AuthClient compatibility methods
+    async getSessionCompat(): Promise<{ session: { token: string } | null } | null> {
+        if (!this.session) return null;
+        return {
+            session: {
+                token: this.session.token
+            }
+        };
+    }
+
+    subscribeCompat(callback: (session: { session: { token: string } | null } | null) => void): () => void {
+        const wrappedCallback = (session: SessionData | null) => {
+            callback(session ? { session: { token: session.token } } : null);
+        };
+        return this.subscribe(wrappedCallback);
+    }
+}
+
+export interface ManagedAuthOptions {
+    storage?: StorageAdapter;
+    autoRefresh?: boolean;
+    refreshBuffer?: number; // Seconds before expiry to refresh (default: 3600)
+}
+
+export interface OfflineOptions {
+    enablePersistence?: boolean;
+    enableImageCache?: boolean;
+    enableUploadQueue?: boolean;
+    persistenceDbName?: string;
+    maxCacheSize?: number; // MB
+    maxDocuments?: number;
+    autoCleanup?: boolean;
+    cleanupThreshold?: number; // 0-1, e.g., 0.9 for 90%
+}
+
+export interface CollabClientOptions {
+    baseUrl: string;
+
+    // Optional: Provide custom auth implementation
+    // If not provided, uses managed auth by default
+    authClient?: AuthClient;
+
+    // Optional: Configure managed auth (only used if authClient not provided)
+    managedAuth?: ManagedAuthOptions;
+
+    // Optional: Configure offline features
+    offline?: OfflineOptions;
+}
+
+export interface ClientExtensionDefinition {
+    name: string;
+    options?: Record<string, any>;
+    scriptUrl?: string;
+}
+
+export interface Document {
+    id: string;
+    name: string;
+    spaceId: string;
+    parentId: string | null;
+    position: number;
+    createdBy: string;
+    createdAt?: string;
+    updatedAt?: string;
+    childrenCount?: number;
+}
+
+export interface DocumentTreeNode extends Document {
+    children: DocumentTreeNode[];
+    depth: number;
+}
+
+export interface Space {
+    id: string;
+    name: string;
+    slug: string;
+    logo?: string | null;
+    createdAt: string;
+    role: string;
+    memberCount?: number;
+    documentCount?: number;
+}
+
+export interface SpaceMember {
+    id: string;
+    userId: string;
+    role: string;
+    user: {
+        name: string;
+        email: string;
+        image?: string;
+    };
+}
+
+export interface FileUpload {
+    id: string;
+    url: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+}
+
+export interface DocumentSnapshot {
+    id: string;
+    createdAt: string;
+    createdBy: string;
+    size: number;
+}
+
+export interface PaginationInfo {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+
+export interface CommentAnchor {
+    from: number;
+    to: number;
+    text: string;
+}
+
+export interface Comment {
+    id: string;
+    documentId: string;
+    spaceId: string;
+    parentId: string | null;
+    authorId: string;
+    authorName: string;
+    content: string;
+    anchor: CommentAnchor | null;
+    resolved: boolean;
+    resolvedBy: string | null;
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface CommentThread extends Comment {
+    replies: Comment[];
+}
+
+export interface CommentEvent {
+    type: "comment" | "comment_error";
+    action: string;
+    data?: any;
+    error?: string;
+    userId: string;
+    timestamp?: number;
+}
+
+// ----------------------------------------------------------------------
+// PersistenceManager (IndexedDB Persistence)
+// ----------------------------------------------------------------------
+
+export interface PersistenceManagerOptions {
+    documentName: string;
+    document: Yjs.Doc;
+    enablePersistence?: boolean;
+    persistenceDbName?: string;
+}
+
+export class PersistenceManager {
+    private persistence: IndexeddbPersistence | null = null;
+    private isReady: boolean = false;
+    private readyPromise: Promise<void>;
+    private listeners: Set<() => void> = new Set();
+
+    constructor(options: PersistenceManagerOptions) {
+        const { documentName, document, enablePersistence = true, persistenceDbName = 'y-collab' } = options;
+
+        if (!enablePersistence || typeof indexedDB === 'undefined') {
+            this.readyPromise = Promise.resolve();
+            this.isReady = true;
+            console.log('[PersistenceManager] Persistence disabled or IndexedDB unavailable');
+            return;
+        }
+
+        // Check for private browsing mode
+        try {
+            const test = indexedDB.open('test');
+            test.onerror = () => {
+                console.warn('[PersistenceManager] IndexedDB not available (private browsing?)');
+                this.readyPromise = Promise.resolve();
+                this.isReady = true;
+            };
+        } catch (e) {
+            console.warn('[PersistenceManager] IndexedDB check failed:', e);
+            this.readyPromise = Promise.resolve();
+            this.isReady = true;
+            return;
+        }
+
+        console.log(`[PersistenceManager] Initializing for ${documentName} in database ${persistenceDbName}`);
+
+        this.persistence = new IndexeddbPersistence(documentName, document);
+
+        this.readyPromise = new Promise<void>((resolve) => {
+            if (!this.persistence) {
+                resolve();
+                return;
+            }
+
+            this.persistence.on('synced', () => {
+                console.log(`[PersistenceManager] Synced from IndexedDB for ${documentName}`);
+                this.isReady = true;
+                this.notifyListeners();
+                resolve();
+            });
+        });
+    }
+
+    public waitForReady(): Promise<void> {
+        return this.readyPromise;
+    }
+
+    public isReadySync(): boolean {
+        return this.isReady;
+    }
+
+    public onReady(callback: () => void): () => void {
+        this.listeners.add(callback);
+        if (this.isReady) {
+            callback();
+        }
+        return () => this.listeners.delete(callback);
+    }
+
+    private notifyListeners(): void {
+        this.listeners.forEach(callback => callback());
+    }
+
+    public async clearData(): Promise<void> {
+        if (this.persistence) {
+            try {
+                await this.persistence.clearData();
+                console.log('[PersistenceManager] Cleared local data');
+            } catch (e) {
+                console.error('[PersistenceManager] Failed to clear data:', e);
+            }
+        }
+    }
+
+    public destroy(): void {
+        if (this.persistence) {
+            this.persistence.destroy();
+            this.persistence = null;
+        }
+        this.listeners.clear();
+    }
+}
+
+// ----------------------------------------------------------------------
+// CollabProviderWebsocket (Shared Connection)
+// ----------------------------------------------------------------------
+
+export interface CollabProviderWebsocketOptions extends Omit<HocuspocusProviderWebsocketConfiguration, "url"> {
+    baseUrl: string;
+    spaceId: string;
+    auth?: AuthClient; // Optional for standalone usage, but Client usually provides it
+    token?: string;
+}
+
+export class CollabProviderWebsocket extends HocuspocusProviderWebsocket {
+    private _authUnsubscribe: (() => void) | null = null;
+    readonly spaceId: string;
+    private _token: string | undefined;
+    private _readyPromise: Promise<void>;
+    private _readyResolve!: () => void;
+    private _spaceDoc: any; // Y.Doc for the space itself
+
+    constructor(options: CollabProviderWebsocketOptions) {
+        const { baseUrl, spaceId, auth, token, ...config } = options;
+
+        // Connect to the collaboration endpoint with spaceId for routing
+        // Matches server route /collaboration/:documentName
+        const url = `${baseUrl.replace(/^http/, 'ws')}/collaboration/space:${spaceId}`;
+        console.log(`[CollabProviderWebsocket] Creating with URL: ${url}, token: ${token ? 'present' : 'missing'}`);
+
+        // HocuspocusProviderWebsocket is just a WebSocket wrapper
+        // Individual HocuspocusProvider instances will attach and send sync messages
+        super({
+            url: (token ? `${url}?token=${token}` : url),
+            ...config,
+        });
+
+        this._spaceDoc = null; // No space doc needed for the WebSocket wrapper
+
+        this._token = token;
+        this.spaceId = spaceId;
+
+        // Set up ready promise
+        this._readyPromise = new Promise<void>((resolve) => {
+            this._readyResolve = resolve;
+
+            // Also resolve immediately if already connected
+            if ((this as any).status === 'connected') {
+                resolve();
+            }
+        });
+
+        // Listen for connection status
+        this.on('status', ({ status }: any) => {
+            console.log(`[CollabProviderWebsocket] Status changed to: ${status}`);
+            if (status === 'connected' && this._readyResolve) {
+                this._readyResolve();
+            }
+        });
+
+        // Debug: Listen to all events
+        this.on('synced', ({ state }: any) => {
+            console.log(`[CollabProviderWebsocket] Synced state: ${state}`);
+        });
+
+        // Message event listener removed - was causing blocking due to JSON.stringify
+
+        this.on('authenticationFailed', ({ reason }: any) => {
+            console.error(`[CollabProviderWebsocket] Authentication failed: ${reason}`);
+        });
+
+        // Awareness update listener removed - was causing blocking
+
+        if (auth && !token) {
+            // Only setup async auth if we don't have a token yet
+            console.log('[CollabProviderWebsocket] No token, setting up auth');
+            this.setupAuth(auth);
+        } else if (auth) {
+            // Setup auth subscription for token refresh, but don't fetch initially
+            console.log('[CollabProviderWebsocket] Token provided, setting up auth subscription only');
+            this._authUnsubscribe = auth.subscribe(async (session: any) => {
+                const newToken = session?.session?.token;
+                if (newToken && newToken !== this._token) {
+                    this.updateToken(newToken);
+                }
+            });
+        }
+    }
+
+    /**
+     * Wait for the websocket to be connected and ready
+     */
+    public async waitForReady(): Promise<void> {
+        // If already connected, resolve immediately
+        if ((this as any).status === 'connected') {
+            return Promise.resolve();
+        }
+        return this._readyPromise;
+    }
+
+    private async setupAuth(auth: AuthClient) {
+        // Subscribe to session changes
+        this._authUnsubscribe = auth.subscribe(async (session: any) => {
+            const token = session?.session?.token;
+            console.log('[CollabProviderWebsocket] Auth subscription callback, token:', token ? 'present' : 'missing');
+            if (token && token !== this._token) {
+                this.updateToken(token);
+            }
+        });
+
+        // Initial fetch if no token provided yet
+        if (!this._token) {
+            console.log('[CollabProviderWebsocket] Fetching initial session...');
+            const session = await auth.getSession();
+            console.log('[CollabProviderWebsocket] Session fetched, token:', session?.session?.token ? 'present' : 'missing');
+            if (session?.session?.token) {
+                this.updateToken(session.session.token);
+                // Connect now that we have the token
+                console.log('[CollabProviderWebsocket] Calling connect()');
+                this.connect();
+            }
+        }
+    }
+
+    private updateToken(newToken: string) {
+        this._token = newToken;
+        // HocuspocusProviderWebsocket doesn't expose a clean way to update query params on the fly
+        // without reconnecting. We assume the server handles auth on connect.
+        // If we want to support seamless token rotation, we might need to send a message or reconnect.
+        // For now, we update the URL generic so next reconnect works.
+        const base = this.configuration.url.toString().split('?')[0];
+        this.configuration.url = `${base}?token=${newToken}`;
+
+        // If we are currently disconnected/connecting, this helps.
+        // If connected, the socket stays open until it expires or we force it.
+        // Some setups prefer forcing reconnect on token change:
+        // this.disconnect();
+        // this.connect();
+    }
+
+    public getToken() {
+        return this._token;
+    }
+
+    public getSpaceDoc() {
+        return this._spaceDoc;
+    }
+
+    destroy() {
+        if (this._authUnsubscribe) {
+            this._authUnsubscribe();
+        }
+        super.destroy();
+    }
+}
+
+// ----------------------------------------------------------------------
+// CollabProvider (Single Document Provider)
+// ----------------------------------------------------------------------
+
+export interface CollabProviderOptions {
+    // Option A: Pass a shared socket (can be base class or our extended class)
+    websocketProvider?: HocuspocusProviderWebsocket | CollabProviderWebsocket;
+
+    // Option B: Standalone mode
+    baseUrl?: string;
+    spaceId?: string;
+    documentId: string;
+    auth?: AuthClient;
+    token?: string | null | (() => string) | (() => Promise<string>);
+
+    // Offline/Persistence options
+    enablePersistence?: boolean;
+    persistenceDbName?: string;
+
+    // Additional provider options
+    document?: any;
+    awareness?: any;
+    onConnect?: () => void;
+    onSynced?: (data: any) => void;
+    onStatus?: (data: any) => void;
+    onAuthenticated?: (data: any) => void;
+    onAuthenticationFailed?: (data: any) => void;
+    onOpen?: (data: any) => void;
+    onMessage?: (data: any) => void;
+    onOutgoingMessage?: (data: any) => void;
+    onDisconnect?: (data: any) => void;
+    onClose?: (data: any) => void;
+    onDestroy?: () => void;
+    onAwarenessUpdate?: (data: any) => void;
+    onAwarenessChange?: (data: any) => void;
+    onStateless?: (data: any) => void;
+    forceSyncInterval?: number | false;
+}
+
+/**
+ * HocuspocusProvider wrapper that handles constructing the correct name/url
+ * based on our platform's conventions.
+ */
+export class CollabProvider extends HocuspocusProvider {
+    private _authUnsubscribe: (() => void) | null = null;
+    readonly documentId: string;
+    private persistenceManager: PersistenceManager | null = null;
+
+    constructor(options: CollabProviderOptions) {
+        const {
+            baseUrl,
+            spaceId,
+            documentId,
+            websocketProvider,
+            auth,
+            token,
+            enablePersistence = true,
+            persistenceDbName,
+            ...providerOptions
+        } = options;
+
+        let config: HocuspocusProviderConfiguration;
+        let parentToken = token;
+
+        // Mode 1: Multiplexing via Shared Socket
+        if (websocketProvider) {
+            const finalSpaceId = spaceId || (websocketProvider instanceof CollabProviderWebsocket ? websocketProvider.spaceId : spaceId);
+            const fullName = `space:${finalSpaceId}:doc:${documentId}`;
+            parentToken = parentToken || (websocketProvider instanceof CollabProviderWebsocket ? websocketProvider.getToken() : undefined);
+
+            console.log(`[CollabProvider] Creating in multiplexing mode`);
+            console.log(`[CollabProvider] Document name: ${fullName}`);
+            console.log(`[CollabProvider] WebsocketProvider status:`, (websocketProvider as any).status);
+            console.log(`[CollabProvider] WebsocketProvider URL:`, (websocketProvider as any).configuration?.url);
+            console.log(`[CollabProvider] Options passed:`, providerOptions);
+
+            config = {
+                name: fullName,
+                websocketProvider: websocketProvider as any,
+                token: parentToken,
+                ...providerOptions
+            } as any;
+
+            console.log(`[CollabProvider] Final config:`, config);
+        }
+        // Mode 2: Standalone Connection
+        else if (baseUrl && spaceId) {
+            const fullName = `space:${spaceId}:doc:${documentId}`;
+            const url = `${baseUrl.replace(/^http/, 'ws')}/collaboration/${fullName}`;
+
+            console.log(`[CollabProvider] Creating in standalone mode`);
+            console.log(`[CollabProvider] URL: ${url}`);
+            console.log(`[CollabProvider] Document name: ${fullName}`);
+
+            config = {
+                url,
+                name: fullName,
+                token,
+                ...providerOptions
+            };
+        } else {
+            throw new Error("CollabProvider requires either 'websocketProvider' or 'baseUrl' + 'spaceId'");
+        }
+
+        super(config);
+        this.documentId = documentId;
+        console.log(`[CollabProvider] Created, status:`, (this as any).status);
+        console.log(`[CollabProvider] Awareness instance present:`, !!this.awareness);
+        console.log(`[CollabProvider] Awareness check:`, this.awareness);
+
+        // Initialize persistence
+        const fullName = config.name as string;
+        this.persistenceManager = new PersistenceManager({
+            documentName: fullName,
+            document: this.document,
+            enablePersistence,
+            persistenceDbName
+        });
+
+        // When using websocketProvider (multiplexing), we must manually attach
+        // The parent constructor only calls attach() if manageSocket is true (standalone mode)
+        // The attach() method will automatically call onOpen() if the websocket is already connected
+        if (websocketProvider) {
+            console.log(`[CollabProvider] Attaching to parent websocket`);
+            console.time('[CollabProvider] attach()');
+            this.attach();
+            console.timeEnd('[CollabProvider] attach()');
+        }
+
+        // Debug: Listen to events
+        this.on('status', ({ status }: any) => {
+            const timestamp = new Date().toISOString()
+            console.log(`[CollabProvider] ${timestamp} Status changed to: ${status}`, {
+                documentId: this.documentId,
+                status: status
+            });
+        });
+
+        this.on('synced', ({ state }: any) => {
+            const timestamp = new Date().toISOString()
+            console.log(`[CollabProvider] ${timestamp} Synced state: ${state}`, {
+                documentId: this.documentId,
+                synced: state
+            });
+        });
+
+        // Message event listener removed - was causing blocking
+
+        this.on('authenticationFailed', ({ reason }: any) => {
+            const timestamp = new Date().toISOString()
+            console.error(`[CollabProvider] ${timestamp} Authentication failed: ${reason}`, {
+                documentId: this.documentId,
+                reason: reason
+            });
+        });
+
+        // Awareness logging removed - was causing blocking
+
+        // Setup auth watchers
+        if (!websocketProvider && auth) {
+            this.setupAuth(auth);
+        } else if (websocketProvider && websocketProvider instanceof CollabProviderWebsocket) {
+            // In multiplexed mode, we might want to listen to the parent socket's token changes?
+            // Actually, HocuspocusProvider reads `this.configuration.token` during authentication steps.
+            // We should ensure `this.configuration.token` is kept fresh.
+            // Currently Hocuspocus doesn't re-read it actively unless we push it.
+        }
+    }
+
+    private async setupAuth(auth: AuthClient) {
+        this._authUnsubscribe = auth.subscribe(async (session: any) => {
+            const token = session?.session?.token;
+            if (token) {
+                this.setToken(token);
+            }
+        });
+
+        const session = await auth.getSession();
+        if (session?.session?.token) {
+            this.setToken(session.session.token);
+        }
+    }
+
+    public setToken(token: string) {
+        this.configuration.token = token;
+        // If connected, send auth message
+        if ((this as any).status === "connected") {
+            this.sendStateless(JSON.stringify({ type: "auth", token: token }));
+        }
+    }
+
+    destroy() {
+        if (this._authUnsubscribe) {
+            this._authUnsubscribe();
+        }
+        if (this.persistenceManager) {
+            this.persistenceManager.destroy();
+        }
+        super.destroy();
+    }
+
+    /**
+     * Wait for persistence to be ready
+     */
+    public async waitForPersistence(): Promise<void> {
+        if (this.persistenceManager) {
+            return this.persistenceManager.waitForReady();
+        }
+    }
+
+    /**
+     * Check if persistence is ready
+     */
+    public isPersistenceReady(): boolean {
+        return this.persistenceManager?.isReadySync() ?? false;
+    }
+
+    /**
+     * Clear local persistence data
+     */
+    public async clearLocalData(): Promise<void> {
+        if (this.persistenceManager) {
+            return this.persistenceManager.clearData();
+        }
+    }
+
+    /**
+     * Send a comment action via stateless message
+     */
+    public sendComment(action: "create" | "update" | "delete" | "resolve", data: any) {
+        this.sendStateless(JSON.stringify({
+            type: "comment",
+            action,
+            data
+        }));
+    }
+
+    /**
+     * Listen for real-time comment events
+     */
+    public onComment(callback: (event: CommentEvent) => void): () => void {
+        const handler = (payload: any) => {
+            try {
+                const msg = JSON.parse(payload.payload);
+                if (msg.type === "comment" || msg.type === "comment_error") {
+                    callback(msg);
+                }
+            } catch (e) {
+                // Ignore parsing errors
+            }
+        };
+        this.on("stateless", handler);
+        return () => this.off("stateless", handler);
+    }
+}
+
+// ----------------------------------------------------------------------
+// CollabClient (Full SDK)
+// ----------------------------------------------------------------------
+
+export class CollabClient {
+    readonly baseUrl: string;
+    readonly auth: AuthClient;
+    private readonly authManager: AuthManager | null = null;
+    private readonly offlineOptions: OfflineOptions;
+
+    // Cache for shared websockets by spaceId
+    private _sockets: Map<string, CollabProviderWebsocket> = new Map();
+    private _token: string | null = null;
+
+    // Upload queue for offline uploads
+    private uploadQueue: UploadQueueManager | null = null;
+
+    constructor(options: CollabClientOptions) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.offlineOptions = {
+            enablePersistence: true,
+            enableImageCache: true,
+            enableUploadQueue: true,
+            persistenceDbName: 'y-collab',
+            maxCacheSize: 50, // MB
+            maxDocuments: 20,
+            autoCleanup: true,
+            cleanupThreshold: 0.9,
+            ...options.offline
+        };
+
+        if (options.authClient) {
+            // Custom auth implementation
+            this.auth = options.authClient;
+        } else {
+            // Managed auth (default)
+            this.authManager = new AuthManager({
+                baseUrl: this.baseUrl,
+                storage: options.managedAuth?.storage,
+                autoRefresh: options.managedAuth?.autoRefresh,
+                refreshBuffer: options.managedAuth?.refreshBuffer
+            });
+
+            this.auth = {
+                getSession: () => this.authManager!.getSessionCompat(),
+                subscribe: (callback) => this.authManager!.subscribeCompat(callback)
+            };
+        }
+
+        this.auth.subscribe((session) => {
+            this._token = session?.session?.token || null;
+        });
+
+        this.auth.getSession().then(s => {
+            this._token = s?.session?.token || null;
+        });
+
+        // Initialize upload queue
+        if (this.offlineOptions.enableUploadQueue && typeof indexedDB !== 'undefined') {
+            this.uploadQueue = new UploadQueueManager();
+            this.uploadQueue.init().catch((error: any) => {
+                console.error('[CollabClient] Failed to initialize upload queue:', error);
+                this.uploadQueue = null;
+            });
+
+            // Process queue when client is created and online
+            if (navigator.onLine) {
+                setTimeout(() => {
+                    this.processUploadQueue().catch(error => {
+                        console.error('[CollabClient] Failed to process upload queue:', error);
+                    });
+                }, 1000);
+            }
+        }
+    }
+
+    // Convenience methods (only available when using managed auth)
+    async login(email: string, password: string): Promise<SessionData> {
+        if (!this.authManager) {
+            throw new Error('login() is only available in managed auth mode');
+        }
+        return this.authManager.login(email, password);
+    }
+
+    async signup(email: string, password: string, name: string): Promise<SessionData> {
+        if (!this.authManager) {
+            throw new Error('signup() is only available in managed auth mode');
+        }
+        return this.authManager.signup(email, password, name);
+    }
+
+    async logout(): Promise<void> {
+        if (!this.authManager) {
+            throw new Error('logout() is only available in managed auth mode');
+        }
+        return this.authManager.logout();
+    }
+
+    getSession(): SessionData | null {
+        if (!this.authManager) {
+            throw new Error('getSession() is only available in managed auth mode');
+        }
+        return this.authManager.getSession();
+    }
+
+    private async getToken(): Promise<string> {
+        if (this._token) return this._token;
+        const session = await this.auth.getSession();
+        this._token = session?.session?.token || null;
+        if (!this._token) {
+            throw new Error("Not authenticated");
+        }
+        return this._token;
+    }
+
+    private async fetch<T>(path: string, options: RequestInit = {}): Promise<T> {
+        const token = await this.getToken();
+        const headers = new Headers(options.headers);
+        headers.set("Authorization", `Bearer ${token}`);
+        if (!headers.has("Content-Type") && !(options.body instanceof FormData)) {
+            headers.set("Content-Type", "application/json");
+        }
+
+        const res = await fetch(`${this.baseUrl}/api${path}`, {
+            ...options,
+            headers,
+        });
+
+        if (!res.ok) {
+            const error = await res.json().catch(() => ({ message: res.statusText }));
+            throw new Error(error.message || error.error || `Request failed: ${res.status}`);
+        }
+
+        // Return empty for 204
+        if (res.status === 204) return {} as T;
+
+        return res.json();
+    }
+
+    // --- Extensions ---
+
+    public async getExtensions(deps?: Record<string, any>): Promise<any[]> {
+        // Make dependencies available for extension scripts that use bare specifiers
+        if (deps) {
+            (globalThis as any).__collab_deps = { ...(globalThis as any).__collab_deps, ...deps };
+        }
+
+        const res = await this.fetch<{ extensions: ClientExtensionDefinition[] }>("/extensions/config");
+        const defs = res.extensions || [];
+        const loadedExtensions: any[] = [];
+
+        for (const def of defs) {
+            if (def.scriptUrl) {
+                try {
+                    const fullUrl = new URL(def.scriptUrl, this.baseUrl).toString();
+                    // Fetch script text and rewrite bare specifiers to use provided deps
+                    const response = await fetch(fullUrl);
+                    const scriptText = await response.text();
+
+                    // Replace bare module specifiers with global deps lookup
+                    const rewritten = scriptText.replace(
+                        /import\s*\{([^}]+)\}\s*from\s*['"]([^./][^'"]*)['"]/g,
+                        (_match, imports, specifier) => {
+                            return `const {${imports}} = globalThis.__collab_deps?.['${specifier}'] ?? (() => { throw new Error('Missing dependency: ${specifier}') })()`;
+                        }
+                    );
+
+                    const blob = new Blob([rewritten], { type: 'application/javascript' });
+                    const blobUrl = URL.createObjectURL(blob);
+
+                    try {
+                        // @ts-ignore
+                        const module = await import(/* @vite-ignore */ blobUrl);
+
+                        if (module.default) {
+                            if (typeof module.default.configure === 'function') {
+                                loadedExtensions.push(module.default.configure(def.options || {}));
+                            } else {
+                                loadedExtensions.push(module.default);
+                            }
+                        }
+                    } finally {
+                        URL.revokeObjectURL(blobUrl);
+                    }
+                } catch (e) {
+                    console.error(`[CollabClient] Failed to load extension ${def.name}`, e);
+                }
+            }
+        }
+        return loadedExtensions;
+    }
+
+    // --- WebSocket / Provider Factory ---
+
+    public async getWebsocketProvider(spaceId: string): Promise<CollabProviderWebsocket> {
+        const cached = this._sockets.get(spaceId);
+
+        // Check if cached socket exists and is still valid (not destroyed)
+        if (cached) {
+            const status = (cached as any).status;
+            const shouldConnect = (cached as any).shouldConnect;
+
+            // Only reuse if the websocket hasn't been destroyed (shouldConnect should be true for active sockets)
+            if (shouldConnect !== false && status !== 'destroyed') {
+                console.log(`[CollabClient] Reusing cached websocket for space: ${spaceId}`);
+                return cached;
+            }
+
+            // Remove destroyed websocket from cache
+            console.log(`[CollabClient] Removing destroyed websocket from cache for space: ${spaceId}`);
+            this._sockets.delete(spaceId);
+        }
+
+        console.log(`[CollabClient] Creating new websocket for space: ${spaceId}`);
+
+        // Get token first before creating websocket
+        const token = await this.getToken();
+        console.log(`[CollabClient] Token obtained:`, token ? 'present' : 'missing');
+
+        const ws = new CollabProviderWebsocket({
+            baseUrl: this.baseUrl,
+            spaceId,
+            auth: this.auth,
+            token, // Pass token directly so it connects immediately
+        });
+
+        this._sockets.set(spaceId, ws);
+        return ws;
+    }
+
+    /**
+     * Get a CollabProvider for a specific document.
+     * Uses a shared WebSocket for the space if possible.
+     */
+    public async getProvider(spaceId: string, documentId: string, options: Partial<HocuspocusProviderConfiguration> = {}): Promise<CollabProvider> {
+        const documentName = `space:${spaceId}:doc:${documentId}`;
+
+        // Check if this document is already attached to the websocket
+        const socket = await this.getWebsocketProvider(spaceId);
+        const providerMap = (socket as any).configuration?.providerMap;
+
+        // CRITICAL: If the same document is already attached, create a NEW websocket
+        // because providerMap.set() overwrites - only one provider per document name per socket
+        if (providerMap && providerMap.has(documentName)) {
+            console.log(`[CollabClient] Document ${documentId} already attached to this websocket - creating separate websocket for this tab`);
+
+            // Create a unique websocket for this tab
+            const token = await this.getToken();
+            const newSocket = new CollabProviderWebsocket({
+                baseUrl: this.baseUrl,
+                spaceId,
+                auth: this.auth,
+                token,
+            });
+
+            // Don't cache this one - it's tab-specific
+            console.log(`[CollabClient] Created separate websocket for tab accessing doc ${documentId}`);
+            await newSocket.waitForReady();
+
+            return new CollabProvider({
+                websocketProvider: newSocket,
+                spaceId,
+                documentId,
+                enablePersistence: this.offlineOptions.enablePersistence,
+                persistenceDbName: this.offlineOptions.persistenceDbName,
+                ...options
+            });
+        }
+
+        // Normal path: document not yet attached, safe to use shared websocket
+        console.log(`[CollabClient] Waiting for websocket to be ready before creating provider for doc ${documentId}`);
+        await socket.waitForReady();
+        console.log(`[CollabClient] Websocket ready, creating provider for doc ${documentId}`);
+
+        return new CollabProvider({
+            websocketProvider: socket,
+            spaceId,
+            documentId,
+            enablePersistence: this.offlineOptions.enablePersistence,
+            persistenceDbName: this.offlineOptions.persistenceDbName,
+            ...options
+        });
+    }
+
+    // --- REST API: Documents ---
+
+    public readonly documents = {
+        /**
+         * List documents in a space
+         * @param parentId - null for root only, undefined for all, string for specific parent
+         */
+        list: (spaceId: string, params?: { parentId?: string | null; limit?: number; offset?: number }) => {
+            const searchParams = new URLSearchParams();
+            if (params?.parentId === null) {
+                searchParams.set('parentId', 'null');
+            } else if (params?.parentId) {
+                searchParams.set('parentId', params.parentId);
+            }
+            if (params?.limit) searchParams.set('limit', String(params.limit));
+            if (params?.offset) searchParams.set('offset', String(params.offset));
+            const qs = searchParams.toString() ? `?${searchParams}` : '';
+            return this.fetch<{ success: true; data: Document[]; pagination: PaginationInfo }>(
+                `/spaces/${spaceId}/documents${qs}`
+            ).then(r => ({ items: r.data, pagination: r.pagination }));
+        },
+
+        get: (spaceId: string, docId: string) =>
+            this.fetch<{ success: true; data: Document }>(`/spaces/${spaceId}/documents/${docId}`).then(r => r.data),
+
+        create: (spaceId: string, options?: { name?: string; parentId?: string | null }) =>
+            this.fetch<Document & { wsUrl: string }>(`/spaces/${spaceId}/documents`, {
+                method: "POST",
+                body: JSON.stringify(options || {}),
+            }),
+
+        update: (spaceId: string, docId: string, data: { name: string }) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/documents/${docId}`, {
+                method: "PATCH",
+                body: JSON.stringify(data),
+            }),
+
+        delete: (spaceId: string, docId: string) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/documents/${docId}`, {
+                method: "DELETE",
+            }),
+
+        getContent: (spaceId: string, docId: string) =>
+            this.fetch<{ id: string; spaceId: string; content: Record<string, unknown> }>(
+                `/spaces/${spaceId}/documents/${docId}/content`
+            ).then(r => r.content),
+
+        /**
+         * Update document content via patch (merge or replace strategy)
+         */
+        patch: (spaceId: string, docId: string, content: any, options?: {
+            merge?: boolean;
+            strategy?: "replace" | "merge" | "append" | "prepend";
+            path?: number[];
+        }) =>
+            this.fetch<{ success: true; document: Document }>(`/spaces/${spaceId}/documents/${docId}/content`, {
+                method: "PATCH",
+                body: JSON.stringify({ content, ...options }),
+            }).then(r => r.document),
+
+        /**
+         * Apply transformation operations to document
+         */
+        transform: (spaceId: string, docId: string, operations: any[]) =>
+            this.fetch<{ success: true; document: Document }>(`/spaces/${spaceId}/documents/${docId}/transform`, {
+                method: "POST",
+                body: JSON.stringify({ operations }),
+            }).then(r => r.document),
+
+        // Hierarchy methods
+        tree: (spaceId: string) =>
+            this.fetch<{ success: true; data: DocumentTreeNode[] }>(`/spaces/${spaceId}/documents/tree`).then(r => r.data),
+
+        children: (spaceId: string, docId: string, params?: { limit?: number; offset?: number }) => {
+            const searchParams = new URLSearchParams();
+            if (params?.limit) searchParams.set('limit', String(params.limit));
+            if (params?.offset) searchParams.set('offset', String(params.offset));
+            const qs = searchParams.toString() ? `?${searchParams}` : '';
+            return this.fetch<{ success: true; data: Document[]; pagination: PaginationInfo }>(
+                `/spaces/${spaceId}/documents/${docId}/children${qs}`
+            ).then(r => ({ items: r.data, pagination: r.pagination }));
+        },
+
+        ancestors: (spaceId: string, docId: string) =>
+            this.fetch<{ success: true; data: Document[] }>(`/spaces/${spaceId}/documents/${docId}/ancestors`).then(r => r.data),
+
+        move: (spaceId: string, docId: string, parentId: string | null, position?: number) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/documents/${docId}/move`, {
+                method: "POST",
+                body: JSON.stringify({ parentId, position }),
+            }),
+
+        // History / Snapshots
+        getSnapshots: (spaceId: string, docId: string) =>
+            this.fetch<{ snapshots: DocumentSnapshot[] }>(`/spaces/${spaceId}/documents/${docId}/snapshots`).then(r => r.snapshots),
+
+        restoreSnapshot: (spaceId: string, docId: string, snapshotId: string) =>
+            this.fetch<{ success: true; message: string }>(`/spaces/${spaceId}/documents/${docId}/restore/${snapshotId}`, {
+                method: "POST",
+            }),
+
+        // Maintenance / Recovery
+        listDeleted: (spaceId: string, params?: { limit?: number; offset?: number }) => {
+            const searchParams = new URLSearchParams();
+            if (params?.limit) searchParams.set('limit', String(params.limit));
+            if (params?.offset) searchParams.set('offset', String(params.offset));
+            const qs = searchParams.toString() ? `?${searchParams}` : '';
+            return this.fetch<{ success: true; data: Document[]; pagination: PaginationInfo }>(
+                `/spaces/${spaceId}/documents/deleted${qs}`
+            ).then(r => ({ items: r.data, pagination: r.pagination }));
+        },
+
+        restore: (spaceId: string, docId: string) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/documents/${docId}/restore`, {
+                method: "POST",
+            }),
+
+        deletePermanent: (spaceId: string, docId: string) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/documents/${docId}/permanent`, {
+                method: "DELETE",
+            }),
+
+        // Export - returns raw HTML string or JSON object depending on format
+        export: async (spaceId: string, docId: string, format: 'html' | 'json' = 'html') => {
+            const token = await this.getToken();
+            const res = await fetch(`${this.baseUrl}/api/spaces/${spaceId}/documents/${docId}/export?format=${format}`, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) throw new Error(`Export failed: ${res.status}`);
+            return format === 'json' ? res.json() : res.text();
+        },
+    };
+
+    // --- REST API: Spaces ---
+
+    public readonly spaces = {
+        list: () =>
+            this.fetch<{ success: true; data: Space[] }>("/spaces").then(r => r.data),
+
+        get: (spaceId: string) =>
+            this.fetch<{ success: true; data: Space }>(`/spaces/${spaceId}`).then(r => r.data),
+
+        getMembers: (spaceId: string) =>
+            this.fetch<{ success: true; data: SpaceMember[] }>(`/spaces/${spaceId}/members`).then(r => r.data),
+
+        create: (data: { name: string; slug?: string }) =>
+            this.fetch<Space>("/organizations", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(data),
+            }),
+
+        /**
+         * Add a member to a space/organization
+         */
+        addMember: (spaceId: string, email: string, role: string) =>
+            this.fetch<{ success: true; memberId: string }>(`/organizations/${spaceId}/members`, {
+                method: "POST",
+                body: JSON.stringify({ email, role }),
+            }),
+
+        /**
+         * Update a member's role
+         */
+        updateRole: (spaceId: string, userId: string, role: string) =>
+            this.fetch<{ success: true }>(`/organizations/${spaceId}/members/${userId}`, {
+                method: "PATCH",
+                body: JSON.stringify({ role }),
+            }),
+
+        /**
+         * Remove a member from a space/organization
+         */
+        removeMember: (spaceId: string, userId: string) =>
+            this.fetch<{ success: true }>(`/organizations/${spaceId}/members/${userId}`, {
+                method: "DELETE",
+            }),
+    };
+
+    // --- REST API: Uploads ---
+
+    public readonly uploads = {
+        list: (spaceId: string, documentId?: string, params?: { limit?: number; offset?: number }) => {
+            const searchParams = new URLSearchParams();
+            if (documentId) searchParams.set('documentId', documentId);
+            if (params?.limit) searchParams.set('limit', String(params.limit));
+            if (params?.offset) searchParams.set('offset', String(params.offset));
+            const qs = searchParams.toString() ? `?${searchParams}` : '';
+            return this.fetch<{ success: true; data: FileUpload[]; pagination: PaginationInfo }>(
+                `/spaces/${spaceId}/files${qs}`
+            ).then(r => ({ items: r.data, pagination: r.pagination }));
+        },
+
+        upload: async (spaceId: string, file: File, documentId?: string) => {
+            // Check if online
+            if (!navigator.onLine && this.uploadQueue) {
+                console.log('[CollabClient] Offline - queuing upload:', file.name);
+
+                // Add to queue and return temp data
+                const pendingUpload = await this.uploadQueue.add({
+                    spaceId,
+                    documentId: documentId || null,
+                    file,
+                    filename: file.name,
+                    mimeType: file.type
+                });
+
+                // Return temporary file info that looks like a FileUpload
+                return {
+                    id: pendingUpload.id,
+                    url: pendingUpload.tempUrl,
+                    filename: pendingUpload.filename,
+                    mimeType: pendingUpload.mimeType,
+                    size: file.size
+                } as FileUpload;
+            }
+
+            // Online - upload directly
+            const formData = new FormData();
+            formData.append("file", file);
+            const qs = documentId ? `?documentId=${documentId}` : "";
+            return this.fetch<{ success: true; data: FileUpload }>(`/spaces/${spaceId}/upload${qs}`, {
+                method: "POST",
+                body: formData,
+            }).then(r => r.data);
+        },
+
+        delete: (spaceId: string, fileId: string) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/files/${fileId}`, {
+                method: "DELETE",
+            }),
+
+        deletePermanent: (spaceId: string, fileId: string) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/files/${fileId}/permanent`, {
+                method: "DELETE",
+            }),
+    };
+
+    // --- REST API: Comments ---
+
+    public readonly comments = {
+        /**
+         * List comments for a document (threaded)
+         */
+        list: (spaceId: string, docId: string) =>
+            this.fetch<{ success: true; data: CommentThread[]; meta: { total: number; resolved: number } }>(
+                `/spaces/${spaceId}/documents/${docId}/comments`
+            ).then(r => ({ threads: r.data, meta: r.meta })),
+
+        /**
+         * Get a single comment
+         */
+        get: (spaceId: string, docId: string, commentId: string) =>
+            this.fetch<{ success: true; data: Comment }>(
+                `/spaces/${spaceId}/documents/${docId}/comments/${commentId}`
+            ).then(r => r.data),
+
+        /**
+         * Create a new comment
+         */
+        create: (spaceId: string, docId: string, data: { content: string; anchor?: CommentAnchor; parentId?: string }) =>
+            this.fetch<{ success: true; data: Comment }>(`/spaces/${spaceId}/documents/${docId}/comments`, {
+                method: "POST",
+                body: JSON.stringify(data),
+            }).then(r => r.data),
+
+        /**
+         * Update a comment's content
+         */
+        update: (spaceId: string, docId: string, commentId: string, content: string) =>
+            this.fetch<{ success: true; data: Comment }>(`/spaces/${spaceId}/documents/${docId}/comments/${commentId}`, {
+                method: "PATCH",
+                body: JSON.stringify({ content }),
+            }).then(r => r.data),
+
+        /**
+         * Delete a comment
+         */
+        delete: (spaceId: string, docId: string, commentId: string) =>
+            this.fetch<{ success: true }>(`/spaces/${spaceId}/documents/${docId}/comments/${commentId}`, {
+                method: "DELETE",
+            }),
+
+        /**
+         * Resolve or unresolve a comment thread
+         */
+        resolve: (spaceId: string, docId: string, commentId: string, resolved: boolean) =>
+            this.fetch<{ success: true; data: Comment }>(`/spaces/${spaceId}/documents/${docId}/comments/${commentId}/resolve`, {
+                method: "POST",
+                body: JSON.stringify({ resolved }),
+            }).then(r => r.data),
+    };
+
+    // --- REST API: Sharing ---
+
+    public readonly share = {
+        /**
+         * Get share status for a document
+         */
+        get: async (spaceId: string, docId: string) => {
+            const token = await this.getToken();
+            const res = await fetch(`${this.baseUrl}/api/spaces/${spaceId}/documents/${docId}/share`, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) throw new Error("Failed to get share status");
+            return res.json() as Promise<{ success: boolean; data: { enabled: boolean; token?: string; access?: string; url?: string } }>;
+        },
+
+        /**
+         * Enable sharing for a document
+         */
+        enable: async (spaceId: string, docId: string) => {
+            const token = await this.getToken();
+            const res = await fetch(`${this.baseUrl}/api/spaces/${spaceId}/documents/${docId}/share`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) throw new Error("Failed to enable sharing");
+            return res.json() as Promise<{ success: boolean; data: { token: string; access: string; url: string } }>;
+        },
+
+        /**
+         * Disable sharing for a document
+         */
+        disable: async (spaceId: string, docId: string) => {
+            const token = await this.getToken();
+            const res = await fetch(`${this.baseUrl}/api/spaces/${spaceId}/documents/${docId}/share`, {
+                method: "DELETE",
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) throw new Error("Failed to disable sharing");
+            return res.json() as Promise<{ success: boolean }>;
+        }
+    };
+
+    /**
+     * Process the upload queue
+     */
+    private async processUploadQueue(): Promise<void> {
+        if (!this.uploadQueue) return;
+
+        await this.uploadQueue.processQueue(async (upload: PendingUpload) => {
+            console.log('[CollabClient] Processing queued upload:', upload.filename);
+
+            // Re-create File from Blob
+            const file = new File([upload.file], upload.filename, { type: upload.mimeType });
+
+            // Upload to server
+            const formData = new FormData();
+            formData.append("file", file);
+            const qs = upload.documentId ? `?documentId=${upload.documentId}` : "";
+
+            const result = await this.fetch<{ success: true; data: FileUpload }>(
+                `/spaces/${upload.spaceId}/upload${qs}`,
+                {
+                    method: "POST",
+                    body: formData,
+                }
+            );
+
+            return result.data;
+        });
+    }
+
+    /**
+     * Get pending uploads count
+     */
+    public async getPendingUploadsCount(): Promise<number> {
+        if (!this.uploadQueue) return 0;
+        return this.uploadQueue.count();
+    }
+
+    /**
+     * Get all pending uploads
+     */
+    public async getPendingUploads(): Promise<PendingUpload[]> {
+        if (!this.uploadQueue) return [];
+        return this.uploadQueue.getAll();
+    }
+
+    /**
+     * Subscribe to upload queue events
+     */
+    public onUploadQueue(event: 'queue-changed' | 'upload-complete' | 'upload-failed', callback: (data: any) => void): () => void {
+        if (!this.uploadQueue) return () => { };
+        return this.uploadQueue.on(event, callback);
+    }
+
+    /**
+     * Get storage quota information
+     */
+    public async getStorageInfo(): Promise<{
+        usage: number;
+        quota: number;
+        percentUsed: number;
+    }> {
+        if (!navigator.storage || !navigator.storage.estimate) {
+            return { usage: 0, quota: 0, percentUsed: 0 };
+        }
+
+        try {
+            const estimate = await navigator.storage.estimate();
+            const usage = estimate.usage || 0;
+            const quota = estimate.quota || 0;
+            const percentUsed = quota > 0 ? (usage / quota) * 100 : 0;
+
+            return { usage, quota, percentUsed };
+        } catch (error) {
+            console.error('[CollabClient] Failed to get storage info:', error);
+            return { usage: 0, quota: 0, percentUsed: 0 };
+        }
+    }
+
+    /**
+     * Clear all local data (IndexedDB and caches)
+     */
+    public async clearAllLocalData(): Promise<void> {
+        console.log('[CollabClient] Clearing all local data...');
+
+        // Clear upload queue
+        if (this.uploadQueue) {
+            await this.uploadQueue.clear();
+        }
+
+        // Clear all IndexedDB databases
+        if (typeof indexedDB !== 'undefined') {
+            try {
+                // Get all database names
+                const databases = await indexedDB.databases();
+                for (const db of databases) {
+                    if (db.name) {
+                        console.log('[CollabClient] Deleting database:', db.name);
+                        await new Promise<void>((resolve, reject) => {
+                            const request = indexedDB.deleteDatabase(db.name!);
+                            request.onsuccess = () => resolve();
+                            request.onerror = () => reject(request.error);
+                        });
+                    }
+                }
+            } catch (error) {
+                console.error('[CollabClient] Failed to clear IndexedDB:', error);
+            }
+        }
+
+        // Clear caches
+        if (typeof caches !== 'undefined') {
+            try {
+                const cacheNames = await caches.keys();
+                for (const name of cacheNames) {
+                    console.log('[CollabClient] Deleting cache:', name);
+                    await caches.delete(name);
+                }
+            } catch (error) {
+                console.error('[CollabClient] Failed to clear caches:', error);
+            }
+        }
+
+        console.log('[CollabClient] Local data cleared');
+    }
+
+    /**
+     * Clear specific document cache
+     */
+    public async clearDocumentCache(spaceId: string, docId: string): Promise<void> {
+        const dbName = this.offlineOptions.persistenceDbName || 'y-collab';
+        const documentName = `space:${spaceId}:doc:${docId}`;
+
+        try {
+            // Open the database and clear the specific document
+            const db = await new Promise<IDBDatabase>((resolve, reject) => {
+                const request = indexedDB.open(dbName);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            });
+
+            // Check if the store exists
+            if (!db.objectStoreNames.contains(documentName)) {
+                db.close();
+                return;
+            }
+
+            // Clear the document store
+            await new Promise<void>((resolve, reject) => {
+                const transaction = db.transaction([documentName], 'readwrite');
+                const store = transaction.objectStore(documentName);
+                const request = store.clear();
+                request.onsuccess = () => resolve();
+                request.onerror = () => reject(request.error);
+            });
+
+            db.close();
+            console.log('[CollabClient] Document cache cleared:', documentName);
+        } catch (error) {
+            console.error('[CollabClient] Failed to clear document cache:', error);
+        }
+    }
+
+    /**
+     * Perform cleanup when storage quota is exceeded
+     */
+    private async performCleanup(): Promise<void> {
+        console.log('[CollabClient] Performing storage cleanup...');
+
+        const { percentUsed } = await this.getStorageInfo();
+        const threshold = (this.offlineOptions.cleanupThreshold || 0.9) * 100;
+
+        if (percentUsed < threshold) {
+            console.log('[CollabClient] Storage usage below threshold, no cleanup needed');
+            return;
+        }
+
+        // Strategy: Clear image cache first (non-critical data)
+        if (typeof caches !== 'undefined') {
+            try {
+                const cacheNames = await caches.keys();
+                for (const name of cacheNames) {
+                    if (name.includes('image')) {
+                        console.log('[CollabClient] Clearing image cache:', name);
+                        await caches.delete(name);
+                    }
+                }
+            } catch (error) {
+                console.error('[CollabClient] Failed to clear image caches:', error);
+            }
+        }
+
+        // Check again
+        const { percentUsed: newPercentUsed } = await this.getStorageInfo();
+        if (newPercentUsed < threshold) {
+            console.log('[CollabClient] Cleanup complete, storage usage:', newPercentUsed, '%');
+            return;
+        }
+
+        // If still over threshold, implement LRU eviction for documents
+        // This is a placeholder - would need to track document access times
+        console.warn('[CollabClient] Storage still over threshold after cleanup');
+    }
+
+    /**
+     * Check storage quota and perform cleanup if needed
+     */
+    public async checkStorageQuota(): Promise<void> {
+        if (!this.offlineOptions.autoCleanup) {
+            return;
+        }
+
+        const { percentUsed } = await this.getStorageInfo();
+        const threshold = (this.offlineOptions.cleanupThreshold || 0.9) * 100;
+
+        if (percentUsed >= threshold) {
+            console.warn('[CollabClient] Storage quota exceeded:', percentUsed, '%');
+            await this.performCleanup();
+        }
+    }
+
+    /**
+     * Get document content using a share token (public access)
+     */
+    public async getPublicContent(spaceId: string, docId: string, shareToken: string) {
+        const res = await fetch(`${this.baseUrl}/api/spaces/${spaceId}/documents/${docId}/content`, {
+            headers: {
+                "Share-Token": shareToken
+            },
+        });
+
+        if (!res.ok) {
+            throw new Error(`Failed to load public document: ${res.status}`);
+        }
+
+        return res.json() as Promise<{ id: string; spaceId: string; content: Record<string, unknown> }>;
+    }
+}