canvu-react 0.3.10 → 0.3.12

package/dist/realtime.cjs

@@ -1744,7 +1744,7 @@ function useRealtimePeerFollow(options) {
   const { viewportRef, sessionPeers, followedPeerId, onFollowEnd } = options;
   const endedPeerIdRef = react.useRef(null);
   const lastAppliedCameraKeyRef = react.useRef(null);
-  const [viewportSizeVersion, setViewportSizeVersion] = react.useState(0);
+  const [, setViewportSizeVersion] = react.useState(0);
   react.useEffect(() => {
     if (!followedPeerId) return;
     let animationFrameId = 0;
@@ -1796,16 +1796,27 @@ function useRealtimePeerFollow(options) {
       return;
     }
     lastAppliedCameraKeyRef.current = nextCameraKey;
-  }, [
-    followedPeerId,
-    onFollowEnd,
-    sessionPeers,
-    viewportRef,
-    viewportSizeVersion
-  ]);
+  }, [followedPeerId, onFollowEnd, sessionPeers, viewportRef]);
 }
 
 // src/react/plugins/realtime/use-realtime-session.ts
+var DRAFT_STORAGE_PREFIX = "canvu-realtime-draft:";
+var DOCUMENT_FLUSH_DEBOUNCE_MS = 120;
+var DRAFT_PERSIST_DEBOUNCE_MS = 420;
+function requestWindowIdleCallback(callback, timeout) {
+  if (typeof window.requestIdleCallback === "function") {
+    return window.requestIdleCallback(callback, { timeout });
+  }
+  return window.setTimeout(callback, timeout);
+}
+function cancelWindowIdleCallback(handle) {
+  if (handle == null) return;
+  if (typeof window.cancelIdleCallback === "function") {
+    window.cancelIdleCallback(handle);
+    return;
+  }
+  window.clearTimeout(handle);
+}
 function createClientId() {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
     return crypto.randomUUID();
@@ -1813,6 +1824,7 @@ function createClientId() {
   return `client-${Math.random().toString(36).slice(2, 10)}`;
 }
 function normalizeSocketUrl(input) {
+  if (!input) return "";
   if (input.startsWith("ws://") || input.startsWith("wss://")) return input;
   if (input.startsWith("http://")) return `ws://${input.slice("http://".length)}`;
   if (input.startsWith("https://")) return `wss://${input.slice("https://".length)}`;
@@ -1831,9 +1843,29 @@ function isValidSocketUrl(input) {
     return false;
   }
 }
+function sanitizeRealtimeItem(item) {
+  if (item.toolKind !== "image") return item;
+  return {
+    ...item,
+    imageBlobId: void 0,
+    imageThumbnailBlobId: void 0,
+    imageRasterHref: void 0,
+    imageThumbnailHref: void 0,
+    childrenSvg: ""
+  };
+}
+function sanitizeRealtimeItems(items) {
+  return items.map(sanitizeRealtimeItem);
+}
+function sanitizeRealtimeSnapshot(snapshot) {
+  return {
+    ...snapshot,
+    items: sanitizeRealtimeItems(snapshot.items)
+  };
+}
 function serializeItems(items) {
   try {
-    return JSON.stringify(items);
+    return JSON.stringify(sanitizeRealtimeItems(items));
   } catch {
     return null;
   }
@@ -1848,6 +1880,58 @@ function sameSerializedItems(left, right) {
 function nowMs() {
   return Date.now();
 }
+function draftStorageKey(roomId) {
+  return `${DRAFT_STORAGE_PREFIX}${roomId}`;
+}
+function isRealtimeOfflineDraft(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return typeof record.roomId === "string" && typeof record.baseRevision === "number" && typeof record.updatedAt === "number" && Array.isArray(record.items);
+}
+function readRealtimeOfflineDraft(roomId) {
+  if (typeof window === "undefined" || !roomId) return null;
+  try {
+    const raw = window.localStorage.getItem(draftStorageKey(roomId));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!isRealtimeOfflineDraft(parsed)) return null;
+    return {
+      ...parsed,
+      items: sanitizeRealtimeItems(parsed.items)
+    };
+  } catch {
+    return null;
+  }
+}
+function writeRealtimeOfflineDraft(draft) {
+  if (typeof window === "undefined") return;
+  if (!draft) return;
+  try {
+    window.localStorage.setItem(
+      draftStorageKey(draft.roomId),
+      JSON.stringify({
+        ...draft,
+        items: sanitizeRealtimeItems(draft.items)
+      })
+    );
+  } catch {
+  }
+}
+function removeRealtimeOfflineDraft(roomId) {
+  if (typeof window === "undefined" || !roomId) return;
+  try {
+    window.localStorage.removeItem(draftStorageKey(roomId));
+  } catch {
+  }
+}
+function buildDraftSnapshot(draft, clientId) {
+  return {
+    revision: draft.baseRevision,
+    items: draft.items,
+    updatedAt: draft.updatedAt,
+    updatedByClientId: clientId
+  };
+}
 function getViewportCameraSnapshot(viewport) {
   if (!viewport) return null;
   const camera = viewport.getCamera();
@@ -1861,6 +1945,17 @@ function getViewportCameraSnapshot(viewport) {
     viewportHeight: viewportSize.height
   };
 }
+function prepareRealtimeItems(items) {
+  try {
+    const sanitizedItems = sanitizeRealtimeItems(items);
+    return {
+      items: sanitizedItems,
+      serialized: JSON.stringify(sanitizedItems)
+    };
+  } catch {
+    return null;
+  }
+}
 function useRealtimeSession(options) {
   const {
     url,
@@ -1879,6 +1974,10 @@ function useRealtimeSession(options) {
   const reconnectTimerRef = react.useRef(null);
   const heartbeatTimerRef = react.useRef(null);
   const connectTimeoutRef = react.useRef(null);
+  const documentFlushTimerRef = react.useRef(null);
+  const documentFlushIdleRef = react.useRef(null);
+  const draftPersistTimerRef = react.useRef(null);
+  const draftPersistIdleRef = react.useRef(null);
   const manualDisconnectRef = react.useRef(false);
   const retryCountRef = react.useRef(0);
   const currentRevisionRef = react.useRef(0);
@@ -1895,6 +1994,8 @@ function useRealtimeSession(options) {
   const connectionStateRef = react.useRef(
     enabled ? "connecting" : "offline"
   );
+  const localDraftRef = react.useRef(null);
+  const conflictRef = react.useRef(null);
   const onErrorRef = react.useRef(onError);
   onErrorRef.current = onError;
   const [connectSequence, setConnectSequence] = react.useState(0);
@@ -1911,7 +2012,18 @@ function useRealtimeSession(options) {
   });
   const [sessionPeers, setSessionPeers] = react.useState([]);
   const [document2, setDocument] = react.useState(null);
+  const [hasLocalOfflineDraft, setHasLocalOfflineDraft] = react.useState(false);
+  const [hasPendingDocumentSync, setHasPendingDocumentSync] = react.useState(false);
+  const [conflict, setConflict] = react.useState(null);
   connectionStateRef.current = connection.state;
+  const syncState = react.useMemo(() => {
+    if (conflict != null) return "conflicted";
+    if (connection.connected) return "connected";
+    if (connection.state === "reconnecting" || connection.state === "connecting") {
+      return "reconnecting";
+    }
+    return "offline";
+  }, [conflict, connection.connected, connection.state]);
   const clearReconnectTimer = react.useCallback(() => {
     if (reconnectTimerRef.current != null) {
       window.clearTimeout(reconnectTimerRef.current);
@@ -1930,6 +2042,22 @@ function useRealtimeSession(options) {
       connectTimeoutRef.current = null;
     }
   }, []);
+  const clearDocumentFlushSchedule = react.useCallback(() => {
+    if (documentFlushTimerRef.current != null) {
+      window.clearTimeout(documentFlushTimerRef.current);
+      documentFlushTimerRef.current = null;
+    }
+    cancelWindowIdleCallback(documentFlushIdleRef.current);
+    documentFlushIdleRef.current = null;
+  }, []);
+  const clearDraftPersistSchedule = react.useCallback(() => {
+    if (draftPersistTimerRef.current != null) {
+      window.clearTimeout(draftPersistTimerRef.current);
+      draftPersistTimerRef.current = null;
+    }
+    cancelWindowIdleCallback(draftPersistIdleRef.current);
+    draftPersistIdleRef.current = null;
+  }, []);
   const updateConnection = react.useCallback(
     (patch) => {
       setConnection((prev) => {
@@ -1955,6 +2083,84 @@ function useRealtimeSession(options) {
     },
     [notifySubscribers]
   );
+  const setConflictState = react.useCallback(
+    (nextConflict) => {
+      conflictRef.current = nextConflict;
+      setConflict(nextConflict);
+    },
+    []
+  );
+  const setLocalDraft = react.useCallback(
+    (nextDraft) => {
+      localDraftRef.current = nextDraft;
+      setHasLocalOfflineDraft(nextDraft != null);
+      if (nextDraft) return;
+      removeRealtimeOfflineDraft(roomId);
+    },
+    [roomId]
+  );
+  const persistLocalDraft = react.useCallback(() => {
+    clearDraftPersistSchedule();
+    if (!localDraftRef.current) {
+      removeRealtimeOfflineDraft(roomId);
+      return;
+    }
+    writeRealtimeOfflineDraft(localDraftRef.current);
+  }, [clearDraftPersistSchedule, roomId]);
+  const scheduleDraftPersistence = react.useCallback(() => {
+    clearDraftPersistSchedule();
+    draftPersistTimerRef.current = window.setTimeout(() => {
+      draftPersistTimerRef.current = null;
+      draftPersistIdleRef.current = requestWindowIdleCallback(() => {
+        draftPersistIdleRef.current = null;
+        persistLocalDraft();
+      }, DRAFT_PERSIST_DEBOUNCE_MS);
+    }, DRAFT_PERSIST_DEBOUNCE_MS);
+  }, [clearDraftPersistSchedule, persistLocalDraft]);
+  const clearLocalDraft = react.useCallback(() => {
+    setLocalDraft(null);
+    clearDraftPersistSchedule();
+  }, [clearDraftPersistSchedule, setLocalDraft]);
+  const createSelfPeer = react.useCallback(
+    (state) => ({
+      id: peer.id,
+      clientId: clientIdRef.current,
+      peerId: peer.id,
+      roomId,
+      joinedAt: connection.lastConnectedAt ?? nowMs(),
+      lastSeenAt: nowMs(),
+      cursor: lastCursorRef.current,
+      isSelf: true,
+      connectionState: state,
+      ...peer.displayName ? { displayName: peer.displayName } : {},
+      ...peer.color ? { color: peer.color } : {},
+      ...peer.image ? { image: peer.image } : {},
+      ...lastMarkupStrokeRef.current !== void 0 ? { markupStroke: lastMarkupStrokeRef.current ?? null } : {},
+      ...lastCameraRef.current !== void 0 ? { camera: lastCameraRef.current ?? null } : {},
+      ...lastActiveToolRef.current ? { activeTool: lastActiveToolRef.current } : {}
+    }),
+    [
+      connection.lastConnectedAt,
+      peer.color,
+      peer.displayName,
+      peer.id,
+      peer.image,
+      roomId
+    ]
+  );
+  const collapsePeersToSelf = react.useCallback(
+    (state) => {
+      setSessionPeers((prev) => {
+        const selfPeer = prev.find(
+          (peerState) => peerState.clientId === clientIdRef.current
+        );
+        return [
+          selfPeer ? { ...selfPeer, isSelf: true, connectionState: state } : createSelfPeer(state)
+        ];
+      });
+    },
+    [createSelfPeer]
+  );
   const applyPeers = react.useCallback((peers) => {
     const selfClientId = clientIdRef.current;
     setSessionPeers(
@@ -1981,30 +2187,102 @@ function useRealtimeSession(options) {
     [buildClientMessage]
   );
   const flushQueuedDocument = react.useCallback(() => {
+    clearDocumentFlushSchedule();
+    if (conflictRef.current) return;
     const next = queuedItemsRef.current;
     if (!next || outboundInFlightRef.current) return;
-    queuedItemsRef.current = null;
     const baseRevision = currentRevisionRef.current;
-    const serialized = serializeItems(next);
-    outboundInFlightRef.current = { baseRevision, items: next, serialized };
-    const didSend = sendRaw({
+    const preparedItems = prepareRealtimeItems(next);
+    if (!preparedItems) return;
+    queuedItemsRef.current = null;
+    outboundInFlightRef.current = {
+      baseRevision,
+      items: preparedItems.items,
+      serialized: preparedItems.serialized
+    };
+    const didSend = sendRawRef.current({
       type: "document:update",
       roomId,
       clientId: clientIdRef.current,
       baseRevision,
-      items: next
+      items: preparedItems.items
     });
     if (!didSend) {
       queuedItemsRef.current = next;
       outboundInFlightRef.current = null;
+      setHasPendingDocumentSync(true);
     }
-  }, [roomId, sendRaw]);
+  }, [clearDocumentFlushSchedule, roomId]);
+  const scheduleDocumentFlush = react.useCallback(() => {
+    clearDocumentFlushSchedule();
+    documentFlushTimerRef.current = window.setTimeout(() => {
+      documentFlushTimerRef.current = null;
+      documentFlushIdleRef.current = requestWindowIdleCallback(() => {
+        documentFlushIdleRef.current = null;
+        flushQueuedDocument();
+      }, DOCUMENT_FLUSH_DEBOUNCE_MS);
+    }, DOCUMENT_FLUSH_DEBOUNCE_MS);
+  }, [clearDocumentFlushSchedule, flushQueuedDocument]);
   const queueDocumentSend = react.useCallback(
     (items) => {
+      setLocalDraft({
+        roomId,
+        baseRevision: currentRevisionRef.current,
+        items,
+        updatedAt: nowMs()
+      });
+      scheduleDraftPersistence();
       queuedItemsRef.current = items;
-      flushQueuedDocument();
+      setHasPendingDocumentSync(true);
+      if (conflictRef.current) return;
+      scheduleDocumentFlushRef.current();
+    },
+    [roomId, scheduleDraftPersistence, setLocalDraft]
+  );
+  const applyDraftSnapshot = react.useCallback(
+    (draft, options2) => {
+      applyDocument(buildDraftSnapshot(draft, clientIdRef.current), options2);
+    },
+    [applyDocument]
+  );
+  const resolveAuthoritativeDocument = react.useCallback(
+    (serverDocument, options2) => {
+      const localDraft = localDraftRef.current;
+      if (!localDraft) {
+        setConflictState(null);
+        setHasPendingDocumentSync(false);
+        applyDocument(serverDocument, options2);
+        return false;
+      }
+      if (sameSerializedItems(localDraft.items, serverDocument.items)) {
+        clearLocalDraftRef.current();
+        setHasPendingDocumentSync(false);
+        setConflictState(null);
+        applyDocument(serverDocument, options2);
+        return true;
+      }
+      if (serverDocument.revision === localDraft.baseRevision) {
+        setConflictState(null);
+        applyDraftSnapshot(localDraft, {
+          suppressSubscriberNotify: options2?.suppressSubscriberNotify ?? sameSerializedItems(latestDocumentRef.current?.items, localDraft.items)
+        });
+        outboundInFlightRef.current = null;
+        queuedItemsRef.current = localDraft.items;
+        setHasPendingDocumentSync(true);
+        scheduleDocumentFlush();
+        return true;
+      }
+      setConflictState({
+        serverRevision: serverDocument.revision,
+        serverItems: serverDocument.items,
+        localItems: localDraft.items
+      });
+      applyDraftSnapshot(localDraft, {
+        suppressSubscriberNotify: options2?.suppressSubscriberNotify ?? sameSerializedItems(latestDocumentRef.current?.items, localDraft.items)
+      });
+      return true;
     },
-    [flushQueuedDocument]
+    [applyDocument, applyDraftSnapshot, scheduleDocumentFlush, setConflictState]
   );
   const sendPresenceUpdate = react.useCallback(() => {
     sendRaw({
@@ -2043,18 +2321,129 @@ function useRealtimeSession(options) {
     reconnect,
     updateConnection
   ]);
+  const resolveConflict = react.useCallback(
+    (action) => {
+      const activeConflict = conflictRef.current;
+      if (!activeConflict) return;
+      if (action === "use-server") {
+        clearLocalDraft();
+        queuedItemsRef.current = null;
+        outboundInFlightRef.current = null;
+        setConflictState(null);
+        applyDocument({
+          revision: activeConflict.serverRevision,
+          items: activeConflict.serverItems,
+          updatedAt: nowMs()
+        });
+        return;
+      }
+      const nextDraft = {
+        roomId,
+        baseRevision: activeConflict.serverRevision,
+        items: activeConflict.localItems,
+        updatedAt: nowMs()
+      };
+      setLocalDraft(nextDraft);
+      scheduleDraftPersistence();
+      setConflictState(null);
+      applyDraftSnapshot(nextDraft, {
+        suppressSubscriberNotify: sameSerializedItems(
+          latestDocumentRef.current?.items,
+          nextDraft.items
+        )
+      });
+      currentRevisionRef.current = activeConflict.serverRevision;
+      queuedItemsRef.current = nextDraft.items;
+      outboundInFlightRef.current = null;
+      setHasPendingDocumentSync(true);
+      scheduleDocumentFlush();
+    },
+    [
+      applyDocument,
+      applyDraftSnapshot,
+      clearLocalDraft,
+      roomId,
+      scheduleDocumentFlush,
+      scheduleDraftPersistence,
+      setConflictState,
+      setLocalDraft
+    ]
+  );
+  const setConflictStateRef = react.useRef(setConflictState);
+  setConflictStateRef.current = setConflictState;
+  const updateConnectionRef = react.useRef(updateConnection);
+  updateConnectionRef.current = updateConnection;
+  const applyDocumentRef = react.useRef(applyDocument);
+  applyDocumentRef.current = applyDocument;
+  const clearLocalDraftRef = react.useRef(clearLocalDraft);
+  clearLocalDraftRef.current = clearLocalDraft;
+  const collapsePeersToSelfRef = react.useRef(collapsePeersToSelf);
+  collapsePeersToSelfRef.current = collapsePeersToSelf;
+  const applyPeersRef = react.useRef(applyPeers);
+  applyPeersRef.current = applyPeers;
+  const resolveAuthoritativeDocumentRef = react.useRef(resolveAuthoritativeDocument);
+  resolveAuthoritativeDocumentRef.current = resolveAuthoritativeDocument;
+  const scheduleDocumentFlushRef = react.useRef(scheduleDocumentFlush);
+  scheduleDocumentFlushRef.current = scheduleDocumentFlush;
+  const scheduleReconnectRef = react.useRef(scheduleReconnect);
+  scheduleReconnectRef.current = scheduleReconnect;
+  const sendRawRef = react.useRef(sendRaw);
+  sendRawRef.current = sendRaw;
+  react.useEffect(() => {
+    if (!roomId) {
+      clearDocumentFlushSchedule();
+      clearDraftPersistSchedule();
+      localDraftRef.current = null;
+      setHasLocalOfflineDraft(false);
+      setHasPendingDocumentSync(false);
+      setConflictState(null);
+      queuedItemsRef.current = null;
+      outboundInFlightRef.current = null;
+      latestDocumentRef.current = null;
+      setDocument(null);
+      currentRevisionRef.current = 0;
+      return;
+    }
+    const localDraft = readRealtimeOfflineDraft(roomId);
+    setLocalDraft(localDraft);
+    setHasPendingDocumentSync(localDraft != null);
+    setConflictState(null);
+    queuedItemsRef.current = localDraft?.items ?? null;
+    outboundInFlightRef.current = null;
+    if (localDraft) {
+      applyDraftSnapshot(localDraft, {
+        suppressSubscriberNotify: sameSerializedItems(
+          latestDocumentRef.current?.items,
+          localDraft.items
+        )
+      });
+    } else {
+      latestDocumentRef.current = null;
+      setDocument(null);
+      currentRevisionRef.current = 0;
+    }
+  }, [
+    applyDraftSnapshot,
+    clearDocumentFlushSchedule,
+    clearDraftPersistSchedule,
+    roomId,
+    setConflictState,
+    setLocalDraft
+  ]);
   react.useEffect(() => {
     if (!enabled) {
       manualDisconnectRef.current = true;
       clearReconnectTimer();
       clearHeartbeatTimer();
       clearConnectTimeout();
+      clearDocumentFlushSchedule();
       wsRef.current?.close();
       wsRef.current = null;
-      setSessionPeers([]);
-      queuedItemsRef.current = null;
+      queuedItemsRef.current = localDraftRef.current?.items ?? null;
       outboundInFlightRef.current = null;
-      updateConnection((prev) => ({
+      setHasPendingDocumentSync(localDraftRef.current != null);
+      collapsePeersToSelfRef.current("offline");
+      updateConnectionRef.current((prev) => ({
         ...prev,
         state: "offline",
         connected: false,
@@ -2065,8 +2454,19 @@ function useRealtimeSession(options) {
     }
     manualDisconnectRef.current = false;
     const socketUrl = normalizeSocketUrl(url);
+    if (!socketUrl) {
+      collapsePeersToSelfRef.current("offline");
+      updateConnectionRef.current((prev) => ({
+        ...prev,
+        state: "offline",
+        connected: false,
+        roomId,
+        lastError: null
+      }));
+      return;
+    }
     if (!isValidSocketUrl(socketUrl)) {
-      updateConnection((prev) => ({
+      updateConnectionRef.current((prev) => ({
         ...prev,
         state: "error",
         connected: false,
@@ -2077,7 +2477,7 @@ function useRealtimeSession(options) {
       return;
     }
     let disposed = false;
-    updateConnection((prev) => ({
+    updateConnectionRef.current((prev) => ({
       ...prev,
       state: retryCountRef.current > 0 ? "reconnecting" : "connecting",
       connected: false,
@@ -2095,7 +2495,7 @@ function useRealtimeSession(options) {
     socket.addEventListener("open", () => {
       if (disposed) return;
       clearConnectTimeout();
-      sendRaw({
+      sendRawRef.current({
         type: "session:join",
         roomId,
         peer: {
@@ -2108,7 +2508,7 @@ function useRealtimeSession(options) {
       });
       clearHeartbeatTimer();
       heartbeatTimerRef.current = window.setInterval(() => {
-        sendRaw({
+        sendRawRef.current({
           type: "session:ping",
           roomId,
           clientId: clientIdRef.current,
@@ -2128,15 +2528,13 @@ function useRealtimeSession(options) {
       }
       const parsed = parseRealtimeServerMessage(payload);
       if (!parsed) return;
-      updateConnection((prev) => ({
+      updateConnectionRef.current((prev) => ({
         ...prev,
         lastMessageAt: nowMs()
       }));
       if (parsed.type === "session:welcome") {
         retryCountRef.current = 0;
-        const queuedBeforeWelcome = queuedItemsRef.current;
-        const shouldPromoteQueuedLocalDraft = queuedBeforeWelcome != null && parsed.document.revision === 0 && parsed.document.items.length === 0;
-        updateConnection((prev) => ({
+        updateConnectionRef.current((prev) => ({
           ...prev,
           state: "connected",
           connected: true,
@@ -2145,19 +2543,26 @@ function useRealtimeSession(options) {
           lastConnectedAt: nowMs(),
           lastError: null
         }));
-        applyPeers(parsed.peers);
-        applyDocument(parsed.document, {
-          suppressSubscriberNotify: shouldPromoteQueuedLocalDraft
-        });
-        if (!shouldPromoteQueuedLocalDraft) {
+        applyPeersRef.current(parsed.peers);
+        const handledByDraft = resolveAuthoritativeDocumentRef.current(
+          sanitizeRealtimeSnapshot(parsed.document),
+          {
+            suppressSubscriberNotify: localDraftRef.current != null && sameSerializedItems(
+              latestDocumentRef.current?.items,
+              localDraftRef.current.items
+            )
+          }
+        );
+        if (!handledByDraft) {
           queuedItemsRef.current = null;
           outboundInFlightRef.current = null;
+          setHasPendingDocumentSync(false);
         }
-        flushQueuedDocument();
+        scheduleDocumentFlushRef.current();
         return;
       }
       if (parsed.type === "presence:sync") {
-        applyPeers(parsed.peers);
+        applyPeersRef.current(parsed.peers);
         return;
       }
       if (parsed.type === "session:peer-joined") {
@@ -2179,14 +2584,14 @@ function useRealtimeSession(options) {
         return;
       }
       if (parsed.type === "session:pong") {
-        updateConnection((prev) => ({
+        updateConnectionRef.current((prev) => ({
           ...prev,
           lastPongAt: parsed.serverTime
         }));
         return;
       }
       if (parsed.type === "session:error") {
-        updateConnection((prev) => ({
+        updateConnectionRef.current((prev) => ({
           ...prev,
           state: prev.connected ? prev.state : "error",
           lastError: parsed.message
@@ -2200,35 +2605,48 @@ function useRealtimeSession(options) {
         const isSelfAck = parsed.document.updatedByClientId === selfClientId;
         if (!isSelfAck) {
           outboundInFlightRef.current = null;
-          queuedItemsRef.current = null;
-          applyDocument(parsed.document);
+          queuedItemsRef.current = localDraftRef.current?.items ?? null;
+          setHasPendingDocumentSync(queuedItemsRef.current != null);
+          resolveAuthoritativeDocumentRef.current(
+            sanitizeRealtimeSnapshot(parsed.document)
+          );
           return;
         }
         const shouldSuppress = inFlight != null && sameSerializedItems(inFlight.items, parsed.document.items);
         outboundInFlightRef.current = null;
-        applyDocument(parsed.document, { suppressSubscriberNotify: shouldSuppress });
+        applyDocumentRef.current(sanitizeRealtimeSnapshot(parsed.document), {
+          suppressSubscriberNotify: shouldSuppress
+        });
         if (queuedItemsRef.current) {
           if (sameSerializedItems(queuedItemsRef.current, parsed.document.items)) {
             queuedItemsRef.current = null;
           } else {
-            flushQueuedDocument();
+            scheduleDocumentFlushRef.current();
           }
         }
+        if (!queuedItemsRef.current) {
+          clearLocalDraftRef.current();
+        }
+        setHasPendingDocumentSync(queuedItemsRef.current != null);
+        setConflictStateRef.current(null);
         return;
       }
       if (parsed.type === "document:resync-required") {
         outboundInFlightRef.current = null;
-        queuedItemsRef.current = null;
-        updateConnection((prev) => ({
+        queuedItemsRef.current = localDraftRef.current?.items ?? null;
+        setHasPendingDocumentSync(queuedItemsRef.current != null);
+        updateConnectionRef.current((prev) => ({
           ...prev,
           lastError: parsed.reason
         }));
-        applyDocument(parsed.document);
+        resolveAuthoritativeDocumentRef.current(
+          sanitizeRealtimeSnapshot(parsed.document)
+        );
       }
     });
     socket.addEventListener("error", () => {
       if (disposed) return;
-      updateConnection((prev) => ({
+      updateConnectionRef.current((prev) => ({
         ...prev,
         state: prev.connected ? prev.state : "error",
         lastError: "Falha de conex\xE3o websocket."
@@ -2239,14 +2657,17 @@ function useRealtimeSession(options) {
       clearHeartbeatTimer();
       clearConnectTimeout();
       wsRef.current = null;
-      updateConnection((prev) => ({
+      collapsePeersToSelfRef.current(
+        manualDisconnectRef.current || !enabled ? "offline" : "reconnecting"
+      );
+      updateConnectionRef.current((prev) => ({
         ...prev,
         connected: false,
         clientId: prev.clientId,
         state: manualDisconnectRef.current || !enabled ? "offline" : prev.state
       }));
       if (!manualDisconnectRef.current && enabled) {
-        scheduleReconnect();
+        scheduleReconnectRef.current();
       }
     });
     return () => {
@@ -2254,27 +2675,23 @@ function useRealtimeSession(options) {
       clearReconnectTimer();
       clearHeartbeatTimer();
       clearConnectTimeout();
+      clearDocumentFlushSchedule();
       socket.close();
     };
   }, [
-    applyDocument,
-    applyPeers,
     clearConnectTimeout,
+    clearDocumentFlushSchedule,
     clearHeartbeatTimer,
     clearReconnectTimer,
     connectSequence,
     connectTimeoutMs,
     enabled,
-    flushQueuedDocument,
     heartbeatMs,
     peer.color,
     peer.displayName,
-    peer.image,
     peer.id,
+    peer.image,
     roomId,
-    scheduleReconnect,
-    sendRaw,
-    updateConnection,
     url
   ]);
   react.useEffect(() => {
@@ -2288,6 +2705,18 @@ function useRealtimeSession(options) {
       )
     );
   }, [connection.state]);
+  react.useEffect(
+    () => () => {
+      clearDocumentFlushSchedule();
+      clearDraftPersistSchedule();
+    },
+    [clearDocumentFlushSchedule, clearDraftPersistSchedule]
+  );
+  const flushDocumentSync = react.useCallback(async () => {
+    persistLocalDraft();
+    if (!connection.connected) return;
+    flushQueuedDocument();
+  }, [connection.connected, flushQueuedDocument, persistLocalDraft]);
   const remoteAdapter = react.useMemo(
     () => ({
       subscribe(onItems) {
@@ -2301,9 +2730,12 @@ function useRealtimeSession(options) {
       },
       send(items) {
         queueDocumentSend(items);
+      },
+      flush() {
+        return flushDocumentSync();
       }
     }),
-    [queueDocumentSend]
+    [flushDocumentSync, queueDocumentSend]
   );
   const disconnect = react.useCallback(() => {
     manualDisconnectRef.current = true;
@@ -2317,6 +2749,7 @@ function useRealtimeSession(options) {
     });
     wsRef.current?.close();
     wsRef.current = null;
+    collapsePeersToSelf("offline");
     updateConnection((prev) => ({
       ...prev,
       state: "offline",
@@ -2326,6 +2759,7 @@ function useRealtimeSession(options) {
     clearConnectTimeout,
     clearHeartbeatTimer,
     clearReconnectTimer,
+    collapsePeersToSelf,
     roomId,
     sendRaw,
     updateConnection
@@ -2391,8 +2825,15 @@ function useRealtimeSession(options) {
     remotePresence,
     remoteAdapter,
     document: document2,
+    hasLocalOfflineDraft,
+    hasPendingDocumentSync,
+    syncState,
+    conflict,
     bindViewportPresence,
     syncViewportPresence,
+    resolveConflict,
+    clearLocalDraft,
+    flushDocumentSync,
     disconnect,
     reconnectNow
   };
@@ -2545,6 +2986,75 @@ function realtimeSessionPlugin(options) {
     render: () => /* @__PURE__ */ jsxRuntime.jsx(RealtimeSessionPanel, { ...options })
   };
 }
+function useRealtimeCanvasDocument(options) {
+  const {
+    session,
+    items,
+    onItemsChange,
+    normalizeItems,
+    hydrateItems,
+    enabled = true
+  } = options;
+  const [loading, setLoading] = react.useState(false);
+  const lastAppliedRevisionRef = react.useRef(null);
+  const realtimeEnabled = enabled && session != null;
+  const applyIncomingItems = react.useCallback(
+    async (nextItems) => {
+      const normalizedItems = normalizeItems ? normalizeItems(nextItems) : [...nextItems];
+      if (!hydrateItems) return normalizedItems;
+      return await hydrateItems(normalizedItems);
+    },
+    [hydrateItems, normalizeItems]
+  );
+  const handleItemsChange = react.useCallback(
+    (nextItems) => {
+      if (!enabled) {
+        onItemsChange?.(normalizeItems ? normalizeItems(nextItems) : nextItems);
+        return;
+      }
+      const normalizedItems = normalizeItems ? normalizeItems(nextItems) : nextItems;
+      onItemsChange?.(normalizedItems);
+      session?.remoteAdapter.send?.(normalizedItems);
+    },
+    [enabled, normalizeItems, onItemsChange, session]
+  );
+  react.useEffect(() => {
+    if (!realtimeEnabled || !onItemsChange || !session?.document) return;
+    if (session.document.updatedByClientId === session.connection.clientId) return;
+    if (lastAppliedRevisionRef.current === session.document.revision) return;
+    let cancelled = false;
+    setLoading(true);
+    void applyIncomingItems(session.document.items).then((resolvedItems) => {
+      if (cancelled) return;
+      lastAppliedRevisionRef.current = session.document?.revision ?? null;
+      onItemsChange(resolvedItems);
+    }).finally(() => {
+      if (cancelled) return;
+      setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [applyIncomingItems, realtimeEnabled, onItemsChange, session]);
+  return react.useMemo(
+    () => ({
+      items,
+      onItemsChange: onItemsChange ? handleItemsChange : void 0,
+      loading,
+      saving: session?.hasPendingDocumentSync ?? false,
+      hasLocalOfflineDraft: session?.hasLocalOfflineDraft ?? false,
+      syncState: session?.syncState ?? "offline",
+      conflict: session?.conflict ?? null,
+      resolveConflict: session?.resolveConflict ?? (() => {
+      }),
+      clearLocalDraft: session?.clearLocalDraft ?? (() => {
+      }),
+      flush: session?.flushDocumentSync ?? (async () => {
+      })
+    }),
+    [handleItemsChange, items, loading, onItemsChange, session]
+  );
+}
 
 exports.PresenceRemoteLayer = PresenceRemoteLayer;
 exports.REALTIME_COMMENT_TOOL = REALTIME_COMMENT_TOOL;
@@ -2563,6 +3073,7 @@ exports.realtimeCollaborationPlugin = realtimeCollaborationPlugin;
 exports.realtimeCommentsPlugin = realtimeCommentsPlugin;
 exports.realtimeSessionPlugin = realtimeSessionPlugin;
 exports.remoteMarkupStrokeFromPlacementPreview = remoteMarkupStrokeFromPlacementPreview;
+exports.useRealtimeCanvasDocument = useRealtimeCanvasDocument;
 exports.useRealtimeComments = useRealtimeComments;
 exports.useRealtimePeerFollow = useRealtimePeerFollow;
 exports.useRealtimeSession = useRealtimeSession;