@agent-native/core 0.85.7 → 0.86.1

package/dist/collab/awareness.d.ts

@@ -29,12 +29,23 @@ export interface AwarenessChangeEvent {
     owner?: string;
     /** Org ID for org-scoped delivery. */
     orgId?: string;
+    /** Shareable resource type this awareness event belongs to, when known. */
+    resourceType?: string;
+    /** Shareable resource id this awareness event belongs to, when known. */
+    resourceId?: string;
+}
+export interface AwarenessScope {
+    owner?: string;
+    orgId?: string;
+    resourceType?: string;
+    resourceId?: string;
 }
 export declare function getAwarenessEmitter(): EventEmitter;
+export declare function rememberAwarenessScope(docId: string, scope: AwarenessScope | undefined): void;
 export declare function emitAwarenessChange(docId: string, states: Array<{
     clientId: number;
     state: string;
-}>, owner?: string, orgId?: string): void;
+}>, scope?: AwarenessScope): void;
 export declare function getDocAwareness(docId: string): Map<number, AwarenessEntry>;
 export declare function cleanExpired(map: Map<number, AwarenessEntry>): void;
 /**

package/dist/collab/awareness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../../src/collab/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAClD,KAAK,CAAC,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAUN;AAKD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAO1E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI,CAOnE;AAUD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;kBAuCa,MAAM;eAAS,MAAM;;;GAa1D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;kBAWM,MAAM;kBAAY,MAAM;;;GAMvD,CAAC"}
+{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../../src/collab/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAe3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD,eAAO,MAAM,sBAAsB,EAAG,kBAA2B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,cAAc,GAAG,SAAS,GAChC,IAAI,CAON;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAClD,KAAK,CAAC,EAAE,cAAc,GACrB,IAAI,CAgBN;AAKD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAO1E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI,CAOnE;AA6BD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;kBAqDa,MAAM;eAAS,MAAM;;;GAoB1D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;kBAYM,MAAM;kBAAY,MAAM;;;GAMvD,CAAC"}

package/dist/collab/awareness.js

@@ -11,7 +11,9 @@
  */
 import { EventEmitter } from "node:events";
 import { defineEventHandler, setResponseStatus, getRouterParam } from "h3";
+import { getSession } from "../server/auth.js";
 import { readBody } from "../server/h3-helpers.js";
+import { deleteAwarenessRow, loadAwarenessRows, upsertAwarenessRow, } from "./awareness-store.js";
 const AWARENESS_TIMEOUT = 30_000; // 30 seconds
 // ---------------------------------------------------------------------------
 // Awareness event emitter — fast-path for push delivery to SSE-connected peers.
@@ -20,17 +22,33 @@ const AWARENESS_TIMEOUT = 30_000; // 30 seconds
 export const AWARENESS_CHANGE_EVENT = "awareness-change";
 const _awarenessEmitter = new EventEmitter();
 _awarenessEmitter.setMaxListeners(0);
+const _awarenessScopes = new Map();
 export function getAwarenessEmitter() {
     return _awarenessEmitter;
 }
-export function emitAwarenessChange(docId, states, owner, orgId) {
+export function rememberAwarenessScope(docId, scope) {
+    if (!scope)
+        return;
+    const next = { ...(_awarenessScopes.get(docId) ?? {}), ...scope };
+    if (!next.owner && !next.orgId && !next.resourceType && !next.resourceId) {
+        return;
+    }
+    _awarenessScopes.set(docId, next);
+}
+export function emitAwarenessChange(docId, states, scope) {
+    rememberAwarenessScope(docId, scope);
+    const resolvedScope = _awarenessScopes.get(docId) ?? {};
     const event = {
         source: "awareness",
         type: "awareness-change",
         docId,
         states,
-        ...(owner && { owner }),
-        ...(orgId && { orgId }),
+        ...(resolvedScope.owner && { owner: resolvedScope.owner }),
+        ...(resolvedScope.orgId && { orgId: resolvedScope.orgId }),
+        ...(resolvedScope.resourceType && {
+            resourceType: resolvedScope.resourceType,
+        }),
+        ...(resolvedScope.resourceId && { resourceId: resolvedScope.resourceId }),
     };
     _awarenessEmitter.emit(AWARENESS_CHANGE_EVENT, event);
 }
@@ -59,6 +77,21 @@ function pruneIfEmpty(docId, map) {
         _awarenessMap.delete(docId);
     }
 }
+/**
+ * Merge SQL-mirrored awareness rows (written by other server instances —
+ * or by an agent action running in its own serverless invocation) into the
+ * in-memory map, newest lastSeen wins. Degrades to memory-only when the DB
+ * is unavailable.
+ */
+async function mergeStoredAwareness(docId, map) {
+    const rows = await loadAwarenessRows(docId);
+    for (const row of rows) {
+        const existing = map.get(row.clientId);
+        if (!existing || row.lastSeen > existing.lastSeen) {
+            map.set(row.clientId, row);
+        }
+    }
+}
 /**
  * POST /_agent-native/collab/:docId/awareness
  *
@@ -73,6 +106,8 @@ export const postAwareness = defineEventHandler(async (event) => {
         setResponseStatus(event, 400);
         return { error: "docId required" };
     }
+    const session = await getSession(event).catch(() => null);
+    const contextScope = event.context?._collabAwarenessScope;
     const body = await readBody(event);
     const { clientId, state } = body;
     if (clientId == null || state === undefined) {
@@ -84,11 +119,20 @@ export const postAwareness = defineEventHandler(async (event) => {
     const map = getDocAwareness(docId);
     if (state === null) {
         map.delete(clientId);
+        // Best-effort cross-instance removal (never blocks the response).
+        void deleteAwarenessRow(docId, clientId);
     }
     else {
         // Store this client's state
-        map.set(clientId, { clientId, state, lastSeen: Date.now() });
+        const entry = { clientId, state, lastSeen: Date.now() };
+        map.set(clientId, entry);
+        // Mirror to SQL so other instances (and serverless action invocations)
+        // see this participant. Throttled internally; never throws.
+        void upsertAwarenessRow(docId, clientId, state, entry.lastSeen);
     }
+    // Pull in participants known to other instances (multi-instance serverless)
+    // before building the response, so every poller sees the full set.
+    await mergeStoredAwareness(docId, map);
     // Clean expired entries, then prune the outer-map entry if it becomes empty.
     // Without pruning, a deployment with many transient docIds (e.g. one per
     // session) would grow _awarenessMap without bound.
@@ -107,7 +151,10 @@ export const postAwareness = defineEventHandler(async (event) => {
     }
     // Fast-path: push the updated state set to SSE-connected peers so they
     // don't have to wait for the next poll cycle for cursor/selection updates.
-    emitAwarenessChange(docId, allStates);
+    emitAwarenessChange(docId, allStates, contextScope ?? {
+        ...(session?.email ? { owner: session.email } : {}),
+        ...(session?.orgId ? { orgId: session.orgId } : {}),
+    });
     return { states: otherStates };
 });
 /**
@@ -122,6 +169,7 @@ export const getActiveUsers = defineEventHandler(async (event) => {
         return { error: "docId required" };
     }
     const map = getDocAwareness(docId);
+    await mergeStoredAwareness(docId, map);
     cleanExpired(map);
     pruneIfEmpty(docId, map);
     const users = [];

package/dist/collab/awareness.js.map

@@ -1 +1 @@
-{"version":3,"file":"awareness.js","sourceRoot":"","sources":["../../src/collab/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAG3E,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,MAAM,iBAAiB,GAAG,MAAM,CAAC,CAAC,aAAa;AAQ/C,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,8EAA8E;AAE9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAA2B,CAAC;AAclE,MAAM,iBAAiB,GAAG,IAAI,YAAY,EAAE,CAAC;AAC7C,iBAAiB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;AAErC,MAAM,UAAU,mBAAmB;IACjC,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,MAAkD,EAClD,KAAc,EACd,KAAc;IAEd,MAAM,KAAK,GAAyB;QAClC,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,kBAAkB;QACxB,KAAK;QACL,MAAM;QACN,GAAG,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC;QACvB,GAAG,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,CAAC;KACxB,CAAC;IACF,iBAAiB,CAAC,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AAED,wCAAwC;AACxC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAuC,CAAC;AAErE,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;QAChB,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAgC;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC;QACpC,IAAI,GAAG,GAAG,KAAK,CAAC,QAAQ,GAAG,iBAAiB,EAAE,CAAC;YAC7C,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,0EAA0E;AAC1E,SAAS,YAAY,CAAC,KAAa,EAAE,GAAgC;IACnE,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACnB,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAC,KAAK,EAAE,KAAc,EAAE,EAAE;IACvE,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAG3B,CAAC;IAEF,IAAI,QAAQ,IAAI,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5C,oEAAoE;QACpE,yEAAyE;QACzE,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;IAClD,CAAC;IAED,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAEnC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,4BAA4B;QAC5B,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,6EAA6E;IAC7E,yEAAyE;IACzE,mDAAmD;IACnD,YAAY,CAAC,GAAG,CAAC,CAAC;IAClB,2EAA2E;IAC3E,4CAA4C;IAC5C,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEzB,wEAAwE;IACxE,MAAM,SAAS,GAA+C,EAAE,CAAC;IACjE,MAAM,WAAW,GAA+C,EAAE,CAAC;IACnE,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC;QAC9B,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACrD,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;YACpB,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,2EAA2E;IAC3E,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAEtC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjC,CAAC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC,KAAK,EAAE,KAAc,EAAE,EAAE;IACxE,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACnC,YAAY,CAAC,GAAG,CAAC,CAAC;IAClB,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEzB,MAAM,KAAK,GAAkD,EAAE,CAAC;IAChE,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Server-side awareness state management for collaborative editing.\n *\n * Stores per-client awareness state (cursor positions, user info) in memory.\n * Clients POST their state and receive other clients' states via polling.\n * States expire after 30 seconds of no updates.\n *\n * Fast-path: when a client POSTs new awareness state, the server emits an\n * event on the awareness emitter so SSE-connected peers receive cursor moves\n * push-style instead of waiting for the next poll cycle.\n */\n\nimport { EventEmitter } from \"node:events\";\n\nimport { defineEventHandler, setResponseStatus, getRouterParam } from \"h3\";\nimport type { H3Event } from \"h3\";\n\nimport { readBody } from \"../server/h3-helpers.js\";\n\nconst AWARENESS_TIMEOUT = 30_000; // 30 seconds\n\nexport interface AwarenessEntry {\n  clientId: number;\n  state: string; // JSON-encoded awareness state object\n  lastSeen: number;\n}\n\n// ---------------------------------------------------------------------------\n// Awareness event emitter — fast-path for push delivery to SSE-connected peers.\n// The SSE handler (poll-events) subscribes and forwards events to its stream.\n// ---------------------------------------------------------------------------\n\nexport const AWARENESS_CHANGE_EVENT = \"awareness-change\" as const;\n\nexport interface AwarenessChangeEvent {\n  source: \"awareness\";\n  type: \"awareness-change\";\n  docId: string;\n  /** Array of updated states for this document (all non-expired clients). */\n  states: Array<{ clientId: number; state: string }>;\n  /** Owner email for access-scoped delivery (taken from session if available). */\n  owner?: string;\n  /** Org ID for org-scoped delivery. */\n  orgId?: string;\n}\n\nconst _awarenessEmitter = new EventEmitter();\n_awarenessEmitter.setMaxListeners(0);\n\nexport function getAwarenessEmitter(): EventEmitter {\n  return _awarenessEmitter;\n}\n\nexport function emitAwarenessChange(\n  docId: string,\n  states: Array<{ clientId: number; state: string }>,\n  owner?: string,\n  orgId?: string,\n): void {\n  const event: AwarenessChangeEvent = {\n    source: \"awareness\",\n    type: \"awareness-change\",\n    docId,\n    states,\n    ...(owner && { owner }),\n    ...(orgId && { orgId }),\n  };\n  _awarenessEmitter.emit(AWARENESS_CHANGE_EVENT, event);\n}\n\n// docId → Map<clientId, AwarenessEntry>\nconst _awarenessMap = new Map<string, Map<number, AwarenessEntry>>();\n\nexport function getDocAwareness(docId: string): Map<number, AwarenessEntry> {\n  let map = _awarenessMap.get(docId);\n  if (!map) {\n    map = new Map();\n    _awarenessMap.set(docId, map);\n  }\n  return map;\n}\n\nexport function cleanExpired(map: Map<number, AwarenessEntry>): void {\n  const now = Date.now();\n  for (const [clientId, entry] of map) {\n    if (now - entry.lastSeen > AWARENESS_TIMEOUT) {\n      map.delete(clientId);\n    }\n  }\n}\n\n// Drop the per-document map from the registry once it has no entries left,\n// so the outer map does not grow unbounded with every docId ever touched.\nfunction pruneIfEmpty(docId: string, map: Map<number, AwarenessEntry>): void {\n  if (map.size === 0) {\n    _awarenessMap.delete(docId);\n  }\n}\n\n/**\n * POST /_agent-native/collab/:docId/awareness\n *\n * Client sends its awareness state and receives other clients' states.\n *\n * Body: { clientId: number, state: string | null (JSON-encoded awareness state, or null to clear) }\n * Response: { states: Array<{ clientId: number, state: string }> }\n */\nexport const postAwareness = defineEventHandler(async (event: H3Event) => {\n  const docId = getRouterParam(event, \"docId\");\n  if (!docId) {\n    setResponseStatus(event, 400);\n    return { error: \"docId required\" };\n  }\n\n  const body = await readBody(event);\n  const { clientId, state } = body as {\n    clientId?: number;\n    state?: string | null;\n  };\n\n  if (clientId == null || state === undefined) {\n    // `!clientId` would wrongly reject clientId === 0, which is a valid\n    // (if rare) Yjs client id. A null state is valid: it clears this client.\n    setResponseStatus(event, 400);\n    return { error: \"clientId and state required\" };\n  }\n\n  const map = getDocAwareness(docId);\n\n  if (state === null) {\n    map.delete(clientId);\n  } else {\n    // Store this client's state\n    map.set(clientId, { clientId, state, lastSeen: Date.now() });\n  }\n\n  // Clean expired entries, then prune the outer-map entry if it becomes empty.\n  // Without pruning, a deployment with many transient docIds (e.g. one per\n  // session) would grow _awarenessMap without bound.\n  cleanExpired(map);\n  // Null-state clears and expiry can empty the map; prune the outer entry so\n  // transient document ids do not accumulate.\n  pruneIfEmpty(docId, map);\n\n  // Build the full list of current states (all clients including sender).\n  const allStates: Array<{ clientId: number; state: string }> = [];\n  const otherStates: Array<{ clientId: number; state: string }> = [];\n  for (const [id, entry] of map) {\n    allStates.push({ clientId: id, state: entry.state });\n    if (id !== clientId) {\n      otherStates.push({ clientId: id, state: entry.state });\n    }\n  }\n\n  // Fast-path: push the updated state set to SSE-connected peers so they\n  // don't have to wait for the next poll cycle for cursor/selection updates.\n  emitAwarenessChange(docId, allStates);\n\n  return { states: otherStates };\n});\n\n/**\n * GET /_agent-native/collab/:docId/users\n *\n * Returns the list of active users for a document (for presence bar).\n */\nexport const getActiveUsers = defineEventHandler(async (event: H3Event) => {\n  const docId = getRouterParam(event, \"docId\");\n  if (!docId) {\n    setResponseStatus(event, 400);\n    return { error: \"docId required\" };\n  }\n\n  const map = getDocAwareness(docId);\n  cleanExpired(map);\n  pruneIfEmpty(docId, map);\n\n  const users: Array<{ clientId: number; lastSeen: number }> = [];\n  for (const [, entry] of map) {\n    users.push({ clientId: entry.clientId, lastSeen: entry.lastSeen });\n  }\n\n  return { users };\n});\n"]}
+{"version":3,"file":"awareness.js","sourceRoot":"","sources":["../../src/collab/awareness.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-side awareness state management for collaborative editing.\n *\n * Stores per-client awareness state (cursor positions, user info) in memory.\n * Clients POST their state and receive other clients' states via polling.\n * States expire after 30 seconds of no updates.\n *\n * Fast-path: when a client POSTs new awareness state, the server emits an\n * event on the awareness emitter so SSE-connected peers receive cursor moves\n * push-style instead of waiting for the next poll cycle.\n */\n\nimport { EventEmitter } from \"node:events\";\n\nimport { defineEventHandler, setResponseStatus, getRouterParam } from \"h3\";\nimport type { H3Event } from \"h3\";\n\nimport { getSession } from \"../server/auth.js\";\nimport { readBody } from \"../server/h3-helpers.js\";\nimport {\n  deleteAwarenessRow,\n  loadAwarenessRows,\n  upsertAwarenessRow,\n} from \"./awareness-store.js\";\n\nconst AWARENESS_TIMEOUT = 30_000; // 30 seconds\n\nexport interface AwarenessEntry {\n  clientId: number;\n  state: string; // JSON-encoded awareness state object\n  lastSeen: number;\n}\n\n// ---------------------------------------------------------------------------\n// Awareness event emitter — fast-path for push delivery to SSE-connected peers.\n// The SSE handler (poll-events) subscribes and forwards events to its stream.\n// ---------------------------------------------------------------------------\n\nexport const AWARENESS_CHANGE_EVENT = \"awareness-change\" as const;\n\nexport interface AwarenessChangeEvent {\n  source: \"awareness\";\n  type: \"awareness-change\";\n  docId: string;\n  /** Array of updated states for this document (all non-expired clients). */\n  states: Array<{ clientId: number; state: string }>;\n  /** Owner email for access-scoped delivery (taken from session if available). */\n  owner?: string;\n  /** Org ID for org-scoped delivery. */\n  orgId?: string;\n  /** Shareable resource type this awareness event belongs to, when known. */\n  resourceType?: string;\n  /** Shareable resource id this awareness event belongs to, when known. */\n  resourceId?: string;\n}\n\nexport interface AwarenessScope {\n  owner?: string;\n  orgId?: string;\n  resourceType?: string;\n  resourceId?: string;\n}\n\nconst _awarenessEmitter = new EventEmitter();\n_awarenessEmitter.setMaxListeners(0);\n\nconst _awarenessScopes = new Map<string, AwarenessScope>();\n\nexport function getAwarenessEmitter(): EventEmitter {\n  return _awarenessEmitter;\n}\n\nexport function rememberAwarenessScope(\n  docId: string,\n  scope: AwarenessScope | undefined,\n): void {\n  if (!scope) return;\n  const next = { ...(_awarenessScopes.get(docId) ?? {}), ...scope };\n  if (!next.owner && !next.orgId && !next.resourceType && !next.resourceId) {\n    return;\n  }\n  _awarenessScopes.set(docId, next);\n}\n\nexport function emitAwarenessChange(\n  docId: string,\n  states: Array<{ clientId: number; state: string }>,\n  scope?: AwarenessScope,\n): void {\n  rememberAwarenessScope(docId, scope);\n  const resolvedScope = _awarenessScopes.get(docId) ?? {};\n  const event: AwarenessChangeEvent = {\n    source: \"awareness\",\n    type: \"awareness-change\",\n    docId,\n    states,\n    ...(resolvedScope.owner && { owner: resolvedScope.owner }),\n    ...(resolvedScope.orgId && { orgId: resolvedScope.orgId }),\n    ...(resolvedScope.resourceType && {\n      resourceType: resolvedScope.resourceType,\n    }),\n    ...(resolvedScope.resourceId && { resourceId: resolvedScope.resourceId }),\n  };\n  _awarenessEmitter.emit(AWARENESS_CHANGE_EVENT, event);\n}\n\n// docId → Map<clientId, AwarenessEntry>\nconst _awarenessMap = new Map<string, Map<number, AwarenessEntry>>();\n\nexport function getDocAwareness(docId: string): Map<number, AwarenessEntry> {\n  let map = _awarenessMap.get(docId);\n  if (!map) {\n    map = new Map();\n    _awarenessMap.set(docId, map);\n  }\n  return map;\n}\n\nexport function cleanExpired(map: Map<number, AwarenessEntry>): void {\n  const now = Date.now();\n  for (const [clientId, entry] of map) {\n    if (now - entry.lastSeen > AWARENESS_TIMEOUT) {\n      map.delete(clientId);\n    }\n  }\n}\n\n// Drop the per-document map from the registry once it has no entries left,\n// so the outer map does not grow unbounded with every docId ever touched.\nfunction pruneIfEmpty(docId: string, map: Map<number, AwarenessEntry>): void {\n  if (map.size === 0) {\n    _awarenessMap.delete(docId);\n  }\n}\n\n/**\n * Merge SQL-mirrored awareness rows (written by other server instances —\n * or by an agent action running in its own serverless invocation) into the\n * in-memory map, newest lastSeen wins. Degrades to memory-only when the DB\n * is unavailable.\n */\nasync function mergeStoredAwareness(\n  docId: string,\n  map: Map<number, AwarenessEntry>,\n): Promise<void> {\n  const rows = await loadAwarenessRows(docId);\n  for (const row of rows) {\n    const existing = map.get(row.clientId);\n    if (!existing || row.lastSeen > existing.lastSeen) {\n      map.set(row.clientId, row);\n    }\n  }\n}\n\n/**\n * POST /_agent-native/collab/:docId/awareness\n *\n * Client sends its awareness state and receives other clients' states.\n *\n * Body: { clientId: number, state: string | null (JSON-encoded awareness state, or null to clear) }\n * Response: { states: Array<{ clientId: number, state: string }> }\n */\nexport const postAwareness = defineEventHandler(async (event: H3Event) => {\n  const docId = getRouterParam(event, \"docId\");\n  if (!docId) {\n    setResponseStatus(event, 400);\n    return { error: \"docId required\" };\n  }\n  const session = await getSession(event).catch(() => null);\n  const contextScope = (\n    event.context as { _collabAwarenessScope?: AwarenessScope } | undefined\n  )?._collabAwarenessScope;\n\n  const body = await readBody(event);\n  const { clientId, state } = body as {\n    clientId?: number;\n    state?: string | null;\n  };\n\n  if (clientId == null || state === undefined) {\n    // `!clientId` would wrongly reject clientId === 0, which is a valid\n    // (if rare) Yjs client id. A null state is valid: it clears this client.\n    setResponseStatus(event, 400);\n    return { error: \"clientId and state required\" };\n  }\n\n  const map = getDocAwareness(docId);\n\n  if (state === null) {\n    map.delete(clientId);\n    // Best-effort cross-instance removal (never blocks the response).\n    void deleteAwarenessRow(docId, clientId);\n  } else {\n    // Store this client's state\n    const entry = { clientId, state, lastSeen: Date.now() };\n    map.set(clientId, entry);\n    // Mirror to SQL so other instances (and serverless action invocations)\n    // see this participant. Throttled internally; never throws.\n    void upsertAwarenessRow(docId, clientId, state, entry.lastSeen);\n  }\n\n  // Pull in participants known to other instances (multi-instance serverless)\n  // before building the response, so every poller sees the full set.\n  await mergeStoredAwareness(docId, map);\n\n  // Clean expired entries, then prune the outer-map entry if it becomes empty.\n  // Without pruning, a deployment with many transient docIds (e.g. one per\n  // session) would grow _awarenessMap without bound.\n  cleanExpired(map);\n  // Null-state clears and expiry can empty the map; prune the outer entry so\n  // transient document ids do not accumulate.\n  pruneIfEmpty(docId, map);\n\n  // Build the full list of current states (all clients including sender).\n  const allStates: Array<{ clientId: number; state: string }> = [];\n  const otherStates: Array<{ clientId: number; state: string }> = [];\n  for (const [id, entry] of map) {\n    allStates.push({ clientId: id, state: entry.state });\n    if (id !== clientId) {\n      otherStates.push({ clientId: id, state: entry.state });\n    }\n  }\n\n  // Fast-path: push the updated state set to SSE-connected peers so they\n  // don't have to wait for the next poll cycle for cursor/selection updates.\n  emitAwarenessChange(\n    docId,\n    allStates,\n    contextScope ?? {\n      ...(session?.email ? { owner: session.email } : {}),\n      ...(session?.orgId ? { orgId: session.orgId } : {}),\n    },\n  );\n\n  return { states: otherStates };\n});\n\n/**\n * GET /_agent-native/collab/:docId/users\n *\n * Returns the list of active users for a document (for presence bar).\n */\nexport const getActiveUsers = defineEventHandler(async (event: H3Event) => {\n  const docId = getRouterParam(event, \"docId\");\n  if (!docId) {\n    setResponseStatus(event, 400);\n    return { error: \"docId required\" };\n  }\n\n  const map = getDocAwareness(docId);\n  await mergeStoredAwareness(docId, map);\n  cleanExpired(map);\n  pruneIfEmpty(docId, map);\n\n  const users: Array<{ clientId: number; lastSeen: number }> = [];\n  for (const [, entry] of map) {\n    users.push({ clientId: entry.clientId, lastSeen: entry.lastSeen });\n  }\n\n  return { users };\n});\n"]}

package/dist/collab/client.d.ts

@@ -30,6 +30,8 @@ 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 {
     /** Document ID to collaborate on. Pass null to disable. */

package/dist/collab/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/collab/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAKzB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;IACnB,uDAAuD;IACvD,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,YAAY,EAAE,OAAO,CAAC;CACvB;AAgBD,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAYD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAY1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EACvC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,OAAO,CA6BT;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,uBAAuB,EAAE,GACtC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CA2B3D;AA6ED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CAgpB3B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/collab/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;IACnB,uDAAuD;IACvD,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,YAAY,EAAE,OAAO,CAAC;CACvB;AAgBD,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjD;AAYD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAY1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EACvC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,OAAO,CA6BT;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,uBAAuB,EAAE,GACtC;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CA2B3D;AA6ED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,yBAAyB,CAolB3B"}

package/dist/collab/client.js

@@ -28,6 +28,7 @@ import { useEffect, useRef, useState, useMemo } from "react";
 import { Awareness } from "y-protocols/awareness";
 import * as Y from "yjs";
 import { agentNativePath } from "../client/api-path.js";
+import { subscribeSyncEvents } from "../client/use-db-sync.js";
 import { AGENT_CLIENT_ID } from "./agent-identity.js";
 // Consistent color palette for user cursors
 const CURSOR_COLORS = [
@@ -412,75 +413,57 @@ export function useCollaborativeDoc(options) {
         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 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);
-                        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);
-                            }
-                        }
-                        // 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);
-                    }
-                };
+        const handleSharedEvent = (change) => {
+            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
+                }
+                if (change.requestSource === "agent") {
+                    setAgentActive(true);
+                    if (agentTimerRef.current)
+                        clearTimeout(agentTimerRef.current);
+                    agentTimerRef.current = setTimeout(() => setAgentActive(false), 3000);
+                }
             }
-            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() {
             return sseActive ? pollIntervalWithSse : pollInterval;
@@ -665,10 +648,7 @@ export function useCollaborativeDoc(options) {
             stopped = true;
             if (timer)
                 clearTimeout(timer);
-            if (sseEventSource) {
-                sseEventSource.close();
-                sseEventSource = null;
-            }
+            unsubscribeSharedEvents();
             window.removeEventListener("focus", pollNow);
             document.removeEventListener("visibilitychange", handleVisibilityChange);
         };
@@ -683,78 +663,58 @@ export function useCollaborativeDoc(options) {
         baseUrl,
         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 = null;
         let stopped = false;
-        function connect() {
-            if (stopped || source)
+        const applyAwarenessEvent = (data) => {
+            if (data.source !== "awareness" ||
+                data.type !== "awareness-change" ||
+                data.docId !== docId) {
                 return;
-            source = new EventSource(sseUrl);
-            source.onmessage = (msg) => {
-                if (stopped)
-                    return;
+            }
+            const states = Array.isArray(data.states)
+                ? data.states
+                : [];
+            const remoteStates = [];
+            for (const remote of states) {
                 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(capturedAwareness.getStates(), 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.
+                    // Invalid state entry — skip
                 }
-            };
-            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);
+            const changes = reconcileRemoteAwarenessStates(capturedAwareness.getStates(), 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);
+            },
+        });
         return () => {
             stopped = true;
-            source?.close();
-            source = null;
-            window.removeEventListener("focus", onFocus);
+            unsubscribe();
         };
     }, [ydoc, docId, awareness]);
     return {