@agent-native/core 0.85.7 → 0.86.1

package/corpus/core/src/collab/client.ts

@@ -30,12 +30,15 @@ import { Awareness } from "y-protocols/awareness";
 import * as Y from "yjs";
 
 import { agentNativePath } from "../client/api-path.js";
+import { subscribeSyncEvents, type SyncEvent } from "../client/use-db-sync.js";
 import { AGENT_CLIENT_ID } from "./agent-identity.js";
 
 export interface CollabUser {
   name: string;
   email: string;
   color: string;
+  /** Profile image shown in presence avatars, cursor flags, and edit tags. */
+  avatarUrl?: string;
 }
 
 export interface UseCollaborativeDocOptions {
@@ -524,92 +527,60 @@ export function useCollaborativeDoc(
 
     // SSE connection state. When SSE is healthy, poll interval is relaxed.
     let sseActive = false;
-    let sseEventSource: EventSource | null = null;
 
     // ── SSE fast-path ────────────────────────────────────────────────
-    // Wire into the framework /_agent-native/events SSE stream.
+    // Subscribe to the SHARED framework transport for /_agent-native/events
+    // instead of opening a dedicated EventSource per collab doc. A tab holds
+    // exactly one SSE connection regardless of how many docs are mounted —
+    // extra streams eat the browser's per-origin connection budget and can
+    // starve regular data fetches (worst on HTTP/1.1 dev servers).
     // 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/events"));
-        sseEventSource = es;
-
-        es.onopen = () => {
-          sseActive = true;
-          consecutiveErrors = 0;
-        };
-
-        es.onmessage = (ev) => {
-          try {
-            const change = JSON.parse(ev.data) as {
-              source?: string;
-              docId?: string;
-              update?: string;
-              requestSource?: string;
-              version?: number;
-            };
-
-            if (
-              change.source === "collab" &&
-              change.docId === docId &&
-              change.update
-            ) {
-              if (requestSource && change.requestSource === requestSource)
-                return;
-              try {
-                Y.applyUpdate(doc, 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,
-                );
-              }
-            }
+    const handleSharedEvent = (change: SyncEvent) => {
+      if (
+        change.source === "collab" &&
+        change.docId === docId &&
+        typeof change.update === "string"
+      ) {
+        if (requestSource && change.requestSource === requestSource) return;
+        try {
+          Y.applyUpdate(doc, base64ToUint8Array(change.update), "remote");
+        } catch {
+          // Malformed update — trigger state-vector fetch on next poll
+        }
 
-            // 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
-          }
-        };
+        if (change.requestSource === "agent") {
+          setAgentActive(true);
+          if (agentTimerRef.current) clearTimeout(agentTimerRef.current);
+          agentTimerRef.current = setTimeout(() => setAgentActive(false), 3000);
+        }
+      }
 
-        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;
+      // Keep pollVersionRef updated from shared-transport 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,
+        );
       }
-    }
+    };
 
-    // Only set up SSE in browser environments that support it.
-    if (typeof EventSource !== "undefined") {
-      initSSE();
-    }
+    const unsubscribeSharedEvents = subscribeSyncEvents({
+      onEvents: (events) => {
+        if (stopped) return;
+        for (const change of events) handleSharedEvent(change);
+      },
+      onSseStateChange: (connected) => {
+        sseActive = connected;
+        if (connected) consecutiveErrors = 0;
+      },
+      pauseWhenHidden,
+    });
 
     // ── Poll loop ───────────────────────────────────────────────────
     function getActivePollInterval(): number {
@@ -831,10 +802,7 @@ export function useCollaborativeDoc(
     return () => {
       stopped = true;
       if (timer) clearTimeout(timer);
-      if (sseEventSource) {
-        sseEventSource.close();
-        sseEventSource = null;
-      }
+      unsubscribeSharedEvents();
       window.removeEventListener("focus", pollNow);
       document.removeEventListener("visibilitychange", handleVisibilityChange);
     };
@@ -850,91 +818,66 @@ export function useCollaborativeDoc(
     docMissing,
   ]);
 
-  // SSE fast-path for awareness: subscribe to the framework events stream and
+  // SSE fast-path for awareness: listen on the SHARED framework transport 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.
+  // Polling fallback keeps working when SSE is unavailable. Reconnection and
+  // focus/visibility handling live inside the shared transport.
   useEffect(() => {
-    if (!ydoc || !docId || !awareness || typeof EventSource === "undefined") {
+    if (!ydoc || !docId || !awareness) {
       return;
     }
     // Non-null captures for closures: null branches returned early above.
     const capturedYdoc = ydoc;
     const capturedAwareness = awareness;
-    const sseUrl = agentNativePath("/_agent-native/events");
-    let source: EventSource | null = null;
     let stopped = false;
 
-    function connect() {
-      if (stopped || source) return;
-      source = new EventSource(sseUrl);
-      source.onmessage = (msg) => {
-        if (stopped) return;
+    const applyAwarenessEvent = (data: SyncEvent) => {
+      if (
+        data.source !== "awareness" ||
+        data.type !== "awareness-change" ||
+        data.docId !== docId
+      ) {
+        return;
+      }
+      const states = Array.isArray(data.states)
+        ? (data.states as Array<{ clientId: number; state: string }>)
+        : [];
+      const remoteStates: RemoteAwarenessSnapshot[] = [];
+      for (const remote of states) {
         try {
-          const data = JSON.parse(msg.data as string) as {
-            source?: string;
-            type?: string;
-            docId?: string;
-            states?: Array<{ clientId: number; state: string }>;
-          };
-          if (
-            data.source !== "awareness" ||
-            data.type !== "awareness-change" ||
-            data.docId !== docId
-          ) {
-            return;
-          }
-          const remoteStates: RemoteAwarenessSnapshot[] = [];
-          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(
-            capturedAwareness.getStates() as Map<number, unknown>,
-            capturedYdoc.clientID,
-            remoteStates,
-          );
-          if (
-            changes.added.length ||
-            changes.updated.length ||
-            changes.removed.length
-          ) {
-            capturedAwareness.emit("change", [changes, "remote"]);
-          }
+          remoteStates.push({
+            clientId: Number(remote.clientId),
+            state: JSON.parse(remote.state),
+          });
         } 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;
+          // Invalid state entry — skip
         }
-      };
-    }
-
-    connect();
-
-    function onFocus() {
-      if (!source || source.readyState === EventSource.CLOSED) {
-        source?.close();
-        source = null;
-        connect();
       }
-    }
+      const changes = reconcileRemoteAwarenessStates(
+        capturedAwareness.getStates() as Map<number, unknown>,
+        capturedYdoc.clientID,
+        remoteStates,
+      );
+      if (
+        changes.added.length ||
+        changes.updated.length ||
+        changes.removed.length
+      ) {
+        capturedAwareness.emit("change", [changes, "remote"]);
+      }
+    };
+
+    const unsubscribe = subscribeSyncEvents({
+      onEvents: (events) => {
+        if (stopped) return;
+        for (const data of events) applyAwarenessEvent(data);
+      },
+    });
 
-    window.addEventListener("focus", onFocus);
     return () => {
       stopped = true;
-      source?.close();
-      source = null;
-      window.removeEventListener("focus", onFocus);
+      unsubscribe();
     };
   }, [ydoc, docId, awareness]);
 

package/corpus/core/src/collab/index.ts

@@ -79,10 +79,44 @@ export {
   agentEnterDocument,
   agentLeaveDocument,
   agentUpdateSelection,
+  agentTouchDocument,
   agentApplyEditsIncrementally,
   agentApplyPatchesIncrementally,
+  AGENT_PRESENCE_LINGER_MS,
+  type AgentLeaveOptions,
+  type AgentTouchOptions,
 } from "./agent-presence.js";
 
+// Recent-edit attribution (lingering highlights)
+export {
+  appendRecentEdit,
+  collectRecentEdits,
+  publishRecentEdit,
+  useRecentEdits,
+  RECENT_EDITS_MAX,
+  RECENT_EDIT_TTL_MS,
+  type RecentEdit,
+  type RecentEditDescriptor,
+  type AttributedRecentEdit,
+  type UseRecentEditsOptions,
+} from "./recent-edits.js";
+
+// Per-user undo/redo
+export {
+  useCollabUndo,
+  useLocalOpUndo,
+  createLocalOpUndoController,
+  type UseCollabUndoOptions,
+  type UseCollabUndoResult,
+  type CollabUndoScope,
+  type UseLocalOpUndoOptions,
+  type UseLocalOpUndoResult,
+  type LocalOpUndoEntry,
+  type LocalOpUndoController,
+  type CreateLocalOpUndoOptions,
+  type UndoKeyboardOptions,
+} from "./undo.js";
+
 // Awareness (re-export for agent-presence consumers)
 export {
   getDocAwareness,

package/corpus/core/src/collab/recent-edits.ts

@@ -0,0 +1,171 @@
+/**
+ * Recent-edit attribution for collaborative documents.
+ *
+ * Every participant (human or agent) may publish a short ring of recent edits
+ * in its awareness state under the `recentEdits` key. Clients render these as
+ * lingering, fading highlights ("Google Docs / Figma collaborator just edited
+ * this") for a few seconds after the edit lands, with the editor's name and
+ * color next to the highlighted region.
+ *
+ * The descriptor is intentionally open-ended — each app publishes whatever its
+ * surfaces can resolve back to a DOM rect:
+ *   - `{ kind: "text", quote }`         rich-text apps resolve by text search
+ *   - `{ kind: "selector", selector }`  canvas/DOM apps resolve by querySelector
+ *   - `{ kind: "paths", paths }`        structured apps resolve JSON paths
+ *     (e.g. `slides.3.content`) to their rendered element
+ *   - `{ kind: "doc" }`                 whole-document change (no region)
+ */
+
+import { useEffect, useRef, useState } from "react";
+
+import type { OtherPresence } from "./presence.js";
+
+export type RecentEditDescriptor =
+  | { kind: "text"; quote: string }
+  | { kind: "selector"; selector: string }
+  | { kind: "paths"; paths: string[] }
+  | { kind: "doc" }
+  | { kind: string; [key: string]: unknown };
+
+export interface RecentEdit {
+  descriptor: RecentEditDescriptor;
+  /** Short human-readable label, e.g. "Rewrote intro" or "Slide 3". */
+  label?: string;
+  /** Epoch ms when the edit landed. */
+  at: number;
+}
+
+/** A recent edit attributed to the participant who made it. */
+export interface AttributedRecentEdit extends RecentEdit {
+  clientId: number;
+  user: OtherPresence["user"];
+  isAgent: boolean;
+}
+
+/** Max entries kept in a participant's recentEdits ring. */
+export const RECENT_EDITS_MAX = 5;
+
+/**
+ * Default time a recent-edit highlight stays visible, measured from the
+ * edit's `at` timestamp. Awareness delivery adds up to ~3s (poll cadence),
+ * and some actions do post-write work before a viewer looks, so this is
+ * deliberately generous — the fade consumes the final 40% of the window.
+ */
+export const RECENT_EDIT_TTL_MS = 10_000;
+
+/**
+ * Append an edit to a recentEdits ring, keeping the newest
+ * {@link RECENT_EDITS_MAX} entries. Pure — returns a new array.
+ */
+export function appendRecentEdit(
+  existing: RecentEdit[] | undefined,
+  edit: RecentEdit,
+): RecentEdit[] {
+  const ring = Array.isArray(existing) ? existing.slice() : [];
+  ring.push(edit);
+  if (ring.length > RECENT_EDITS_MAX) {
+    ring.splice(0, ring.length - RECENT_EDITS_MAX);
+  }
+  return ring;
+}
+
+/**
+ * Flatten non-expired recent edits from remote participants, newest last.
+ * Pure — exported for tests and non-React consumers.
+ */
+export function collectRecentEdits(
+  others: OtherPresence[],
+  ttlMs: number,
+  now: number,
+): AttributedRecentEdit[] {
+  const result: AttributedRecentEdit[] = [];
+  for (const other of others) {
+    const ring = other.presence["recentEdits"];
+    if (!Array.isArray(ring)) continue;
+    for (const raw of ring) {
+      const edit = raw as RecentEdit;
+      if (!edit || typeof edit.at !== "number" || !edit.descriptor) continue;
+      if (now - edit.at > ttlMs) continue;
+      result.push({
+        ...edit,
+        clientId: other.clientId,
+        user: other.user,
+        isAgent: other.isAgent,
+      });
+    }
+  }
+  result.sort((a, b) => a.at - b.at);
+  return result;
+}
+
+export interface UseRecentEditsOptions {
+  /** How long a highlight lingers after the edit. Default 6000ms. */
+  ttlMs?: number;
+}
+
+/**
+ * Reactive list of remote participants' recent edits that haven't expired.
+ * Ticks internally (~500ms) while any highlight is visible so consumers can
+ * render a smooth fade-out without wiring their own timers.
+ */
+export function useRecentEdits(
+  others: OtherPresence[],
+  options?: UseRecentEditsOptions,
+): AttributedRecentEdit[] {
+  const ttlMs = options?.ttlMs ?? RECENT_EDIT_TTL_MS;
+  const [edits, setEdits] = useState<AttributedRecentEdit[]>([]);
+  const othersRef = useRef(others);
+  othersRef.current = others;
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    function tick() {
+      const next = collectRecentEdits(othersRef.current, ttlMs, Date.now());
+      setEdits((prev) => (recentEditsEqual(prev, next) ? prev : next));
+      if (next.length > 0) {
+        timer = setTimeout(tick, 500);
+      } else {
+        timer = null;
+      }
+    }
+
+    tick();
+    return () => {
+      if (timer) clearTimeout(timer);
+    };
+  }, [others, ttlMs]);
+
+  return edits;
+}
+
+/**
+ * Publish a local edit into this client's awareness ring so peers render a
+ * lingering highlight for it. Call from app mutation paths (throttled by the
+ * ring size + TTL; safe to call per committed edit, not per keystroke).
+ */
+export function publishRecentEdit(
+  awareness: {
+    getLocalState: () => Record<string, unknown> | null;
+    setLocalStateField: (field: string, value: unknown) => void;
+  },
+  edit: Omit<RecentEdit, "at"> & { at?: number },
+): void {
+  const local = awareness.getLocalState();
+  const existing = local?.["recentEdits"] as RecentEdit[] | undefined;
+  awareness.setLocalStateField(
+    "recentEdits",
+    appendRecentEdit(existing, { ...edit, at: edit.at ?? Date.now() }),
+  );
+}
+
+function recentEditsEqual(
+  a: AttributedRecentEdit[],
+  b: AttributedRecentEdit[],
+): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].clientId !== b[i].clientId || a[i].at !== b[i].at) return false;
+  }
+  return true;
+}