@agent-native/core 0.45.1 → 0.47.1

package/dist/collab/client.js

@@ -7,6 +7,22 @@
  *
  * Also manages Yjs Awareness for cursor positions and user presence,
  * synced via polling to the server's awareness endpoint.
+ *
+ * Transport improvements (vs previous version):
+ * - Local update POSTs are debounced and coalesced with Y.mergeUpdates (~80ms)
+ *   to avoid per-keystroke requests. The batch is flushed immediately on
+ *   visibilitychange/pagehide and before each poll/awareness cycle.
+ * - GET state?stateVector= is NOT fetched on every poll cycle. It is fetched:
+ *   (a) on (re)connect / initial load, (b) when a poll response indicates a
+ *   gap (version jump > ring-buffer size), (c) after applying an update fails,
+ *   and (d) as a low-frequency safety net every STATE_VECTOR_FETCH_INTERVAL
+ *   poll cycles (~15×).
+ * - Network errors use exponential backoff with jitter (cap ~15s), reset on
+ *   success.
+ * - SSE fast-path: collab events are received push-style from
+ *   /_agent-native/poll-events (the existing SSE stream). While SSE is
+ *   healthy the poll loop relaxes to a slow cadence (10–15s). If SSE is
+ *   unavailable the 2s poll resumes automatically.
  */
 import { useEffect, useRef, useState, useMemo } from "react";
 import * as Y from "yjs";
@@ -151,8 +167,48 @@ function base64ToUint8Array(b64) {
     }
     return arr;
 }
+/** Debounce delay for coalescing local Yjs update POSTs (ms). */
+const UPDATE_DEBOUNCE_MS = 80;
+/** Fetch state-vector every N poll cycles as a low-frequency safety net. */
+const STATE_VECTOR_FETCH_INTERVAL = 15;
+/** Poll ring-buffer size on the server (MAX_BUFFER in poll.ts). */
+const POLL_RING_BUFFER_SIZE = 200;
+/** Exponential backoff: base delay (ms), multiplier, cap (ms). */
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_MAX_MS = 15_000;
+function calcBackoff(consecutiveErrors) {
+    const exp = Math.min(consecutiveErrors, 10);
+    const delay = BACKOFF_BASE_MS * Math.pow(2, exp);
+    // Add jitter: ±25%
+    const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+    return Math.min(delay + jitter, BACKOFF_MAX_MS);
+}
+// ---------------------------------------------------------------------------
+// Fast awareness helper — throttled per (docId, ydocId) pair so multiple
+// setLocalStateField calls within a 150ms window are coalesced into one POST.
+// ---------------------------------------------------------------------------
+const _awarenessThrottleTimers = new Map();
+function scheduleAwarenessPush(baseUrl, docId, clientId, getState) {
+    if (typeof window === "undefined")
+        return;
+    const key = `${docId}::${clientId}`;
+    if (_awarenessThrottleTimers.has(key))
+        return; // already scheduled
+    const timer = setTimeout(() => {
+        _awarenessThrottleTimers.delete(key);
+        const state = getState();
+        if (!state)
+            return;
+        fetch(`${baseUrl}/${docId}/awareness`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ clientId, state: JSON.stringify(state) }),
+        }).catch(() => { }); // best-effort; poll cycle is the baseline fallback
+    }, 150);
+    _awarenessThrottleTimers.set(key, timer);
+}
 export function useCollaborativeDoc(options) {
-    const { docId, pollInterval = 2000, pauseWhenHidden = true, baseUrl = agentNativePath("/_agent-native/collab"), requestSource, user, } = options;
+    const { docId, pollInterval = 2000, pollIntervalWithSse = 12000, pauseWhenHidden = true, baseUrl = agentNativePath("/_agent-native/collab"), requestSource, user, } = options;
     // Stable Y.Doc per docId
     const ydoc = useMemo(() => {
         if (!docId)
@@ -190,6 +246,23 @@ export function useCollaborativeDoc(options) {
         });
         awareness.setLocalStateField("visible", !isDocumentHidden());
     }, [awareness, user?.name, user?.email, user?.color]);
+    // Fast awareness push: whenever local state changes (e.g. cursor moves,
+    // setPresence() calls), schedule a throttled POST so peers receive updates
+    // at ~150ms instead of waiting for the next 2s poll cycle. The poll cycle
+    // remains the authoritative baseline (cursors degrade gracefully without SSE).
+    useEffect(() => {
+        if (!awareness || !ydoc || !docId || !user)
+            return;
+        const clientId = ydoc.clientID;
+        const onLocalStateChange = () => {
+            scheduleAwarenessPush(baseUrl, docId, clientId, () => awareness.getLocalState());
+        };
+        // awareness emits "change" for local state changes too (when origin is "local").
+        awareness.on("change", onLocalStateChange);
+        return () => {
+            awareness.off("change", onLocalStateChange);
+        };
+    }, [awareness, ydoc, docId, baseUrl, user]);
     // Track active users from awareness changes
     useEffect(() => {
         if (!awareness)
@@ -262,56 +335,206 @@ export function useCollaborativeDoc(options) {
             cancelled = true;
         };
     }, [ydoc, docId, baseUrl]);
-    // Send local updates to server
+    // Send local updates to server — debounced and coalesced with Y.mergeUpdates.
+    //
+    // Instead of firing one POST per Yjs update (one per keystroke), we accumulate
+    // updates in a buffer for UPDATE_DEBOUNCE_MS then merge them into a single
+    // request. The buffer is also flushed immediately on visibilitychange/pagehide
+    // and before each poll/awareness cycle so we don't hold stale local state.
     useEffect(() => {
         if (!ydoc || !docId || docMissing)
             return;
-        const handler = (update, origin) => {
-            if (origin === "remote")
+        let pendingUpdates = [];
+        let flushTimer = null;
+        const flushPendingUpdates = (keepalive = false) => {
+            if (flushTimer) {
+                clearTimeout(flushTimer);
+                flushTimer = null;
+            }
+            if (pendingUpdates.length === 0)
                 return;
+            const toSend = pendingUpdates;
+            pendingUpdates = [];
+            const merged = toSend.length === 1 ? toSend[0] : Y.mergeUpdates(toSend);
             fetch(`${baseUrl}/${docId}/update`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
-                    update: uint8ArrayToBase64(update),
+                    update: uint8ArrayToBase64(merged),
                     requestSource,
                 }),
-            });
+                ...(keepalive ? { keepalive: true } : {}),
+            }).catch(() => { });
+        };
+        // Expose flush to the poll loop via a ref so it can flush before each cycle.
+        // We store the flusher in a closure-captured variable; the poll effect
+        // below reads it through the shared `pendingFlushRef`.
+        ydoc.__collabFlush = flushPendingUpdates;
+        const handler = (update, origin) => {
+            if (origin === "remote")
+                return;
+            pendingUpdates.push(update);
+            if (flushTimer)
+                clearTimeout(flushTimer);
+            flushTimer = setTimeout(flushPendingUpdates, UPDATE_DEBOUNCE_MS);
+        };
+        const handlePageHide = () => {
+            flushPendingUpdates(true /* keepalive */);
         };
         ydoc.on("update", handler);
+        if (typeof window !== "undefined") {
+            window.addEventListener("pagehide", handlePageHide);
+        }
         return () => {
             ydoc.off("update", handler);
+            delete ydoc.__collabFlush;
+            if (typeof window !== "undefined") {
+                window.removeEventListener("pagehide", handlePageHide);
+            }
+            // Flush any remaining updates on teardown
+            flushPendingUpdates(true);
         };
     }, [ydoc, docId, baseUrl, requestSource, docMissing]);
-    // Poll for remote doc updates + awareness sync
+    // Poll for remote doc updates + awareness sync, with SSE fast-path.
     useEffect(() => {
         if (!ydoc || !docId || docMissing)
             return;
         let stopped = false;
         let timer = null;
+        let consecutiveErrors = 0;
+        let pollCycleCount = 0;
+        // Track the last version we successfully polled. Used to detect ring-buffer
+        // overflow (version gap larger than the ring buffer).
+        let lastPolledVersion = pollVersionRef.current;
+        // SSE connection state. When SSE is healthy, poll interval is relaxed.
+        let sseActive = false;
+        let sseEventSource = null;
+        // ── SSE fast-path ────────────────────────────────────────────────
+        // Wire into the existing /_agent-native/poll-events SSE stream.
+        // Collab update events arrive push-style; we apply them immediately,
+        // avoiding ~2s polling latency for peer edits.
+        //
+        // NOTE: SSE events are subject to the same server-side access scoping as
+        // polling — the server only pushes events that canSeeChangeForUser allows.
+        // The server tags collab events with owner/orgId (security commit).
+        function initSSE() {
+            if (typeof EventSource === "undefined")
+                return;
+            try {
+                const es = new EventSource(agentNativePath("/_agent-native/poll-events"));
+                sseEventSource = es;
+                es.onopen = () => {
+                    sseActive = true;
+                    consecutiveErrors = 0;
+                };
+                es.onmessage = (ev) => {
+                    try {
+                        const change = JSON.parse(ev.data);
+                        if (change.source === "collab" &&
+                            change.docId === docId &&
+                            change.update) {
+                            if (requestSource && change.requestSource === requestSource)
+                                return;
+                            try {
+                                Y.applyUpdate(ydoc, base64ToUint8Array(change.update), "remote");
+                            }
+                            catch {
+                                // Malformed update — trigger state-vector fetch on next poll
+                            }
+                            if (change.requestSource === "agent") {
+                                setAgentActive(true);
+                                if (agentTimerRef.current)
+                                    clearTimeout(agentTimerRef.current);
+                                agentTimerRef.current = setTimeout(() => setAgentActive(false), 3000);
+                            }
+                        }
+                        // Keep pollVersionRef updated from SSE events so the poll loop
+                        // starts from the right version when SSE drops.
+                        if (typeof change.version === "number") {
+                            pollVersionRef.current = Math.max(pollVersionRef.current, change.version);
+                        }
+                    }
+                    catch {
+                        // Ignore malformed events
+                    }
+                };
+                es.onerror = () => {
+                    sseActive = false;
+                    es.close();
+                    sseEventSource = null;
+                    // Retry SSE after a short delay
+                    if (!stopped) {
+                        setTimeout(initSSE, 5_000 + Math.random() * 5_000);
+                    }
+                };
+            }
+            catch {
+                // SSE not available (edge runtime, etc.) — fall back to polling only
+                sseActive = false;
+            }
+        }
+        // Only set up SSE in browser environments that support it.
+        if (typeof EventSource !== "undefined") {
+            initSSE();
+        }
+        // ── Poll loop ───────────────────────────────────────────────────
+        function getActivePollInterval() {
+            return sseActive ? pollIntervalWithSse : pollInterval;
+        }
         function schedulePoll() {
             if (stopped)
                 return;
             if (pauseWhenHidden && isDocumentHidden())
                 return;
-            timer = setTimeout(poll, pollInterval);
+            timer = setTimeout(poll, getActivePollInterval());
+        }
+        async function fetchStateVector() {
+            try {
+                const stateVector = uint8ArrayToBase64(Y.encodeStateVector(ydoc));
+                const stateRes = await fetch(`${baseUrl}/${docId}/state?stateVector=${encodeURIComponent(stateVector)}`);
+                if (stateRes.ok) {
+                    const stateData = (await stateRes.json().catch(() => null));
+                    if (stateData?.state) {
+                        const binary = base64ToUint8Array(stateData.state);
+                        if (binary.length > 2) {
+                            Y.applyUpdate(ydoc, binary, "remote");
+                        }
+                    }
+                }
+            }
+            catch {
+                // Non-fatal; the next poll cycle will retry
+            }
         }
         async function poll() {
             if (stopped)
                 return;
+            // Flush any pending local updates before polling so the server has the
+            // latest state before we read remote changes.
+            const flush = ydoc.__collabFlush;
+            flush?.();
             try {
-                // Poll for document updates
                 const res = await fetch(agentNativePath(`/_agent-native/poll?since=${pollVersionRef.current}`));
                 if (!res.ok)
                     throw new Error("HTTP " + res.status);
                 const data = await res.json();
                 const { version, events } = data;
+                // Detect ring-buffer overflow: if the version jumped by more than the
+                // ring buffer size, some events were evicted and we need a state-vector
+                // fetch to reconcile the gap.
+                const versionGap = version - lastPolledVersion;
+                const hadGap = versionGap > POLL_RING_BUFFER_SIZE;
                 for (const evt of events) {
                     if (evt.source === "collab" && evt.docId === docId && evt.update) {
                         if (requestSource && evt.requestSource === requestSource)
                             continue;
-                        Y.applyUpdate(ydoc, base64ToUint8Array(evt.update), "remote");
-                        // Show agent presence indicator briefly
+                        try {
+                            Y.applyUpdate(ydoc, base64ToUint8Array(evt.update), "remote");
+                        }
+                        catch {
+                            // Failed to apply — fetch full state-vector below
+                            await fetchStateVector();
+                        }
                         if (evt.requestSource === "agent") {
                             setAgentActive(true);
                             if (agentTimerRef.current)
@@ -321,64 +544,67 @@ export function useCollaborativeDoc(options) {
                     }
                 }
                 pollVersionRef.current = version;
-                try {
-                    // The poll ring buffer is process-local. Fetching a state-vector diff
-                    // makes collaboration durable across serverless invocations, process
-                    // restarts, or any missed poll event.
-                    const stateVector = uint8ArrayToBase64(Y.encodeStateVector(ydoc));
-                    const stateRes = await fetch(`${baseUrl}/${docId}/state?stateVector=${encodeURIComponent(stateVector)}`);
-                    if (stateRes.ok) {
-                        const stateData = (await stateRes.json().catch(() => null));
-                        if (stateData?.state) {
-                            const binary = base64ToUint8Array(stateData.state);
-                            if (binary.length > 2) {
-                                Y.applyUpdate(ydoc, binary, "remote");
-                            }
-                        }
-                    }
-                }
-                catch {
-                    // The next poll retries; awareness should still sync below.
+                lastPolledVersion = version;
+                pollCycleCount++;
+                consecutiveErrors = 0;
+                // Fetch state-vector only when needed:
+                //   1. Ring-buffer overflow detected (missed events).
+                //   2. Low-frequency safety net every STATE_VECTOR_FETCH_INTERVAL cycles.
+                //   3. NOT on every cycle (the previous behavior causing 3 requests/cycle).
+                const shouldFetchStateVector = hadGap || pollCycleCount % STATE_VECTOR_FETCH_INTERVAL === 0;
+                if (shouldFetchStateVector) {
+                    await fetchStateVector();
                 }
                 // Sync awareness (cursor positions)
                 if (awareness) {
                     const localState = awareness.getLocalState();
                     if (localState) {
-                        const awarenessRes = await fetch(`${baseUrl}/${docId}/awareness`, {
-                            method: "POST",
-                            headers: { "Content-Type": "application/json" },
-                            body: JSON.stringify({
-                                clientId: ydoc.clientID,
-                                state: JSON.stringify(localState),
-                            }),
-                        });
-                        if (awarenessRes.ok) {
-                            const awarenessData = await awarenessRes.json();
-                            const remoteStates = [];
-                            for (const remote of awarenessData.states || []) {
-                                try {
-                                    const remoteState = JSON.parse(remote.state);
-                                    remoteStates.push({
-                                        clientId: Number(remote.clientId),
-                                        state: remoteState,
-                                    });
+                        try {
+                            const awarenessRes = await fetch(`${baseUrl}/${docId}/awareness`, {
+                                method: "POST",
+                                headers: { "Content-Type": "application/json" },
+                                body: JSON.stringify({
+                                    clientId: ydoc.clientID,
+                                    state: JSON.stringify(localState),
+                                }),
+                            });
+                            if (awarenessRes.ok) {
+                                const awarenessData = await awarenessRes.json();
+                                const remoteStates = [];
+                                for (const remote of awarenessData.states || []) {
+                                    try {
+                                        const remoteState = JSON.parse(remote.state);
+                                        remoteStates.push({
+                                            clientId: Number(remote.clientId),
+                                            state: remoteState,
+                                        });
+                                    }
+                                    catch {
+                                        // Invalid state — skip
+                                    }
                                 }
-                                catch {
-                                    // Invalid state — skip
+                                const changes = reconcileRemoteAwarenessStates(awareness.getStates(), ydoc.clientID, remoteStates);
+                                if (changes.added.length ||
+                                    changes.updated.length ||
+                                    changes.removed.length) {
+                                    awareness.emit("change", [changes, "remote"]);
                                 }
                             }
-                            const changes = reconcileRemoteAwarenessStates(awareness.getStates(), ydoc.clientID, remoteStates);
-                            if (changes.added.length ||
-                                changes.updated.length ||
-                                changes.removed.length) {
-                                awareness.emit("change", [changes, "remote"]);
-                            }
+                        }
+                        catch {
+                            // Awareness sync failure is non-fatal
                         }
                     }
                 }
             }
             catch {
-                // Network error — retry next interval
+                // Network error — exponential backoff
+                consecutiveErrors++;
+                const backoff = calcBackoff(consecutiveErrors);
+                if (!stopped) {
+                    timer = setTimeout(poll, backoff);
+                    return;
+                }
             }
             schedulePoll();
         }
@@ -394,7 +620,7 @@ export function useCollaborativeDoc(options) {
         // Publish this tab's visibility to peers. A hidden tab pauses its poll, so
         // we push the state immediately (keepalive) instead of waiting for the next
         // cycle — otherwise peers keep treating a backgrounded tab as the visible
-        // lead and an agent edit never lands on the tab the user is looking at.
+        // lead and an agent edit never lands on the tab the user is actually viewing.
         function publishVisibility(visible) {
             if (!awareness)
                 return;
@@ -416,6 +642,9 @@ export function useCollaborativeDoc(options) {
             const visible = document.visibilityState === "visible";
             publishVisibility(visible);
             if (visible) {
+                // Also flush any pending updates when coming back into view
+                const flush = ydoc.__collabFlush;
+                flush?.();
                 pollNow();
             }
             else if (pauseWhenHidden && timer) {
@@ -432,6 +661,10 @@ export function useCollaborativeDoc(options) {
             stopped = true;
             if (timer)
                 clearTimeout(timer);
+            if (sseEventSource) {
+                sseEventSource.close();
+                sseEventSource = null;
+            }
             window.removeEventListener("focus", pollNow);
             document.removeEventListener("visibilitychange", handleVisibilityChange);
         };
@@ -440,11 +673,83 @@ export function useCollaborativeDoc(options) {
         awareness,
         docId,
         pollInterval,
+        pollIntervalWithSse,
         pauseWhenHidden,
         requestSource,
         baseUrl,
         docMissing,
     ]);
+    // SSE fast-path for awareness: subscribe to the poll-events stream and
+    // apply any awareness-change events immediately so peers receive cursor
+    // moves push-style without waiting for the next poll cycle.
+    // Polling fallback keeps working when SSE is unavailable.
+    useEffect(() => {
+        if (!ydoc || !docId || !awareness || typeof EventSource === "undefined") {
+            return;
+        }
+        const sseUrl = agentNativePath("/_agent-native/poll-events");
+        let source = null;
+        let stopped = false;
+        function connect() {
+            if (stopped || source)
+                return;
+            source = new EventSource(sseUrl);
+            source.onmessage = (msg) => {
+                if (stopped)
+                    return;
+                try {
+                    const data = JSON.parse(msg.data);
+                    if (data.source !== "awareness" ||
+                        data.type !== "awareness-change" ||
+                        data.docId !== docId) {
+                        return;
+                    }
+                    const remoteStates = [];
+                    for (const remote of data.states ?? []) {
+                        try {
+                            remoteStates.push({
+                                clientId: Number(remote.clientId),
+                                state: JSON.parse(remote.state),
+                            });
+                        }
+                        catch {
+                            // Invalid state entry — skip
+                        }
+                    }
+                    const changes = reconcileRemoteAwarenessStates(awareness.getStates(), ydoc.clientID, remoteStates);
+                    if (changes.added.length ||
+                        changes.updated.length ||
+                        changes.removed.length) {
+                        awareness.emit("change", [changes, "remote"]);
+                    }
+                }
+                catch {
+                    // Ignore malformed SSE frames; poll cycle is the safety net.
+                }
+            };
+            source.onerror = () => {
+                // On permanent close let go of the ref so re-focus can reconnect.
+                if (source && source.readyState === EventSource.CLOSED) {
+                    source = null;
+                }
+            };
+        }
+        connect();
+        function onFocus() {
+            if (!source || source.readyState === EventSource.CLOSED) {
+                source?.close();
+                source = null;
+                connect();
+            }
+        }
+        window.addEventListener("focus", onFocus);
+        return () => {
+            stopped = true;
+            source?.close();
+            source = null;
+            window.removeEventListener("focus", onFocus);
+        };
+    }, [ydoc, docId, awareness]);
     return {
         ydoc,
         awareness,