real-time-collab

# Real-Time Collaboration ## Rule Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are equal participants — both edit the same Y.Doc and changes merge cleanly without conflicts. Always choose an explicit `access` mode on `createCollabPlugin`. ## How It Works - **`Y.Doc`** stores the document as a `Y.XmlFragment` (ProseMirror node tree) - **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment via `ySyncPlugin` - **CollaborationCaret extension** renders remote users' cursors with names and colors - **SSE fast-path** — `/_agent-native/poll-events` `EventSource` delivers collab events push-style; while SSE is healthy the collab poll interval relaxes to ~12 s - **Polling fallback** — `/_agent-native/poll` is polled every 2 s when SSE is unavailable; this is the universal serverless fallback - **Update batching** — local Yjs updates are debounced ~80 ms and coalesced with `Y.mergeUpdates` before sending; flushed immediately on `visibilitychange` / `pagehide` - **SQL `_collab_docs` table** persists Yjs state as base64 (SQLite/Postgres compatible). Tombstone compaction fires automatically when the stored blob exceeds 4× the fresh encoded size. ## Agent + Human Editing 1. **Human edits** → TipTap → ySyncPlugin → Y.XmlFragment → `POST /_agent-native/collab/:docId/update` 2. **Agent edits** → action edits canonical SQL content + bumps `updatedAt` → change-sync refetch → the open editor reconciles the new content into the live Y.Doc (see below) → poll update → all clients Both produce Yjs operations that merge cleanly. Agent edits appear without destroying cursor position, selection, or undo history. The agent does **not** push edits into Yjs in-process and does **not** call any localhost probe — those approaches silently no-op on serverless (the action runs in a different process). The peer-editor model below replaced them. ## Agent Edits As A Real-Time Peer Editor **SQL is the durable source of truth for document body content.** The agent action edits the canonical content column and bumps `updatedAt`. No localhost calls, no in-process Yjs mutation. **The open editor reconciles authoritative external content into the live Y.Doc.** The `updatedAt` bump flows through change-sync, which refetches the record. The lead client applies the new content via `setContent`, producing Yjs operations that merge with concurrent human edits. Every connected client receives the result through normal Yjs sync. ### The `updatedAt` gate ```ts // In the editor's reconcile effect if (loaded.updatedAt > lastAppliedUpdatedAt.current) { applyAuthoritativeContent(loaded.content); // adopt lastAppliedUpdatedAt.current = loaded.updatedAt; } // else: lagging poll / stale snapshot → ignore ``` Without the gate, a slightly-behind poll response re-applies old content and the edit "reverts on next poll". A fresh mount always adopts whatever content it loaded. ### Lead-client election Exactly ONE connected client applies the authoritative snapshot; the rest receive it through Yjs sync: ```ts import { isReconcileLeadClient } from "@agent-native/core/client/collab"; if ( loaded.updatedAt > lastAppliedUpdatedAt.current && isReconcileLeadClient(awareness, ydoc.clientID) ) { applyAuthoritativeContent(loaded.content); } ``` The agent's awareness entry (`AGENT_CLIENT_ID`, max int) can never be the lead. A sole client is always the lead. The election is deterministic with no coordination round-trip. ### v1 limitation Full-content reconcile is **last-writer-wins** for the rare case where a human has unsaved edits in the exact region the agent simultaneously rewrites. Edits in **different** regions merge fine through the CRDT. ## Security ### Always choose an explicit access mode Inspect the schema and sharing registration before configuring collaboration: - For owned or shareable records, use `mode: "resource"` and the resource type registered through `registerShareableResource`. - For records deliberately visible to every authenticated user on the deployment, use `mode: "all-authenticated"`. - Never invent a `resourceType` merely to silence a warning. Resource mode is correct only when the matching ownership and sharing model exists. ```ts // server/plugins/collab.ts import { createCollabPlugin } from "@agent-native/core/server"; export default createCollabPlugin({ table: "documents", contentColumn: "content", idColumn: "id", access: { mode: "resource", resourceType: "document" }, }); ``` For intentionally deployment-wide authenticated collaboration: ```ts createCollabPlugin({ table: "todos", contentColumn: "content", access: { mode: "all-authenticated" }, }); ``` Omitting `access` is supported only for legacy compatibility and is deprecated. It behaves like `all-authenticated`, logs a warning, and is flagged by Doctor. Choose the mode explicitly so access intent is reviewable. Non-owner sharees who have explicit access fall back to state-vector catch-up (safe, slightly higher latency). Awareness routes require the same viewer access as read routes. ### Payload limits Write routes reject payloads exceeding `maxPayloadBytes` (default 2 MB) with HTTP 413. Override: ```ts createCollabPlugin({ access: { mode: "resource", resourceType: "document" }, maxPayloadBytes: 512 * 1024, }); ``` ## Enabling Collaboration ### 1. Install packages ```bash pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core ``` ### 2. Add collab server plugin (with explicit access) ```ts // server/plugins/collab.ts import { createCollabPlugin } from "@agent-native/core/server"; export default createCollabPlugin({ table: "documents", contentColumn: "content", idColumn: "id", access: { mode: "resource", resourceType: "document" }, }); ``` ### 3. Use the client hook ```ts import { useCollaborativeDoc, emailToColor, emailToName } from "@agent-native/core/client/collab"; const { ydoc, awareness, activeUsers, agentActive, agentPresent } = useCollaborativeDoc({ docId: documentId, requestSource: TAB_ID, user: { name: emailToName(session.email), email: session.email, color: emailToColor(session.email), }, }); ``` ### 4. Add TipTap extensions ```ts import { Collaboration } from "@tiptap/extension-collaboration"; import { CollaborationCaret } from "@tiptap/extension-collaboration-caret"; const editor = useEditor({ extensions: [ StarterKit.configure({ history: false }), // Yjs handles undo Collaboration.configure({ document: ydoc }), CollaborationCaret.configure({ provider: { awareness }, user: { name: session.email, color: "#6366f1" }, }), ], // Do NOT pass content — Yjs owns it }); ``` ### 5. Add to vite.config.ts optimizeDeps ```ts optimizeDeps: { include: [ "yjs", "y-protocols/awareness", "@tiptap/core", "@tiptap/extension-collaboration", "@tiptap/extension-collaboration-caret", "@tiptap/y-tiptap", ], } ``` ## Collab Routes (auto-mounted) | Route | Purpose | | ----- | ------- | | `GET /_agent-native/collab/:docId/state` | Fetch full Y.Doc state (accepts `?stateVector=` for diff) | | `POST /_agent-native/collab/:docId/update` | Apply client Yjs update | | `POST /_agent-native/collab/:docId/text` | Apply full text (diff-based) | | `POST /_agent-native/collab/:docId/search-replace` | Surgical find/replace in Y.XmlFragment | | `POST /_agent-native/collab/:docId/json` | Apply full JSON diff to Y.Map/Y.Array | | `GET /_agent-native/collab/:docId/json` | Read current JSON state | | `POST /_agent-native/collab/:docId/patch` | Surgical JSON patch ops | | `POST /_agent-native/collab/:docId/awareness` | Sync cursor/presence state | | `GET /_agent-native/collab/:docId/users` | List active users | ## Granular Server-Side Merge Pattern For structured documents (slides, forms, design files) where body collab would cause LWW conflicts at the container level, use **granular server-side merge**: define an action with targeted per-item operations. **When to use granular merge vs body collab:** | Scenario | Recommended approach | | -------- | -------------------- | | Free-form rich text, cursor-level CRDT matters | Body collab (Y.XmlFragment + TipTap) | | Structured items (slides, fields) where different users edit different items | Granular server-side merge (action with patch ops) | Example operation shape for slides: ```ts type PatchDeckOp = | { type: "patch"; slideId: string; fields: Partial<SlideFields> } | { type: "add"; position: number; slide: SlideData } | { type: "delete"; slideId: string } | { type: "reorder"; slideId: string; newIndex: number }; ``` Concurrent edits to different slides both succeed at the action level; there is no whole-deck LWW. Forms use the same shape with field-level ops. ## Agent Presence & Lingering Edit Highlights The agent is a *visible* collaborator, not a silent content-swapper. Core handles most of this automatically: - **Auto-presence on agent writes** — any `applyText` / `searchAndReplace` / `applyJson` / `applyPatchOps` call with `requestSource: "agent"` publishes an agent awareness entry plus a `recentEdits` attribution describing what changed. Actions that route writes through the collab layer get full presence UX with zero extra wiring. - **Linger** — `agentLeaveDocument` (and the auto-presence path) keeps the agent's awareness entry alive for ~6s (`AGENT_PRESENCE_LINGER_MS`) after the last edit so viewers see who just changed what. Pass `{ lingerMs: 0 }` to clear immediately. On serverless the linger degrades to the 30s awareness expiry. - **`agentTouchDocument(docId, { edit, metadata })`** — refcount-neutral presence + attribution for actions that write SQL directly (no collab doc). `edit.descriptor` is one of `{kind:"text",quote}`, `{kind:"selector",selector}`, `{kind:"paths",paths}`, `{kind:"doc"}`. - **Durable across instances** — awareness is mirrored to the additive `_collab_awareness` table, so presence written by an action in one serverless invocation is visible to clients polling any other instance. Client rendering: ```tsx import { usePresence, useRecentEdits, RecentEditHighlights, PresenceBar, LiveCursorOverlay, RemoteSelectionRings, } from "@agent-native/core/client/collab"; const { others, setPresence } = usePresence(awareness, ydoc?.clientID); const recentEdits = useRecentEdits(others); // non-expired, ~6s TTL <RecentEditHighlights edits={recentEdits} containerRef={containerRef} resolveRect={(edit) => /* map descriptor → DOMRect, or null */ null} /> ``` Humans get the same treatment: call `publishRecentEdit(awareness, { descriptor })` from local mutation paths so peers see lingering highlights for human edits too. `CollabUser.avatarUrl` puts faces on avatars, cursors, and edit tags. ## Per-User Undo (never revert someone else's work) Undo must only reverse the local user's edits — and must never restore a whole-document snapshot (that clobbers concurrent edits by peers/the agent). Core ships two primitives: **Yjs surfaces — `useCollabUndo`** (wraps `Y.UndoManager` lifecycle): ```ts import { useCollabUndo } from "@agent-native/core/client/collab"; const { undo, redo, canUndo, canRedo, transactLocal, localOrigin } = useCollabUndo({ ydoc, scope: (doc) => doc.getText("content"), captureTimeout: 500, enableKeyboardShortcuts: true, // Mod+Z / Shift+Mod+Z / Mod+Y }); // Tag every local mutation so it is captured: transactLocal(() => { /* mutate shared types */ }); ``` Remote (`"remote"`) and agent (`"agent"`/`"server"`) origins are never captured. The manager is recreated/destroyed automatically when `ydoc` changes. (TipTap's Collaboration extension already provides this behavior for its own editor content.) **Op-based surfaces (slides/forms) — `useLocalOpUndo`**: record inverse granular ops for each local mutation; undo replays the inverse ops through your normal granular mutation path: ```ts const { push, undo, redo, canUndo, canRedo } = useLocalOpUndo({ apply: (ops) => applyGranularOps(ops), // your patch path }); push({ undo: [{ type: "patch", slideId, fields: prevFields }], redo: [{ type: "patch", slideId, fields: nextFields }], coalesceKey: `${slideId}:content`, // merge rapid bursts into one step }); ``` Entries whose target no longer exists should fail soft (skip), never reset the whole history — external/agent edits must not wipe the user's undo stack. ## Common Pitfalls - **Missing `access`** — Legacy omission behaves like `all-authenticated`, logs a startup warning, and is flagged by Doctor. Choose `resource` for records backed by ownership/sharing, or explicit `all-authenticated` for intentionally deployment-wide records. Never invent a resource type to silence the warning. - **Don't pass `content` as a TipTap prop** when Collaboration is enabled — Yjs owns the content. Seed via `editor.commands.setContent()` only when the Y.XmlFragment is empty. - **Don't call `editor.setContent()` ad hoc for agent edits** — the only sanctioned `setContent` is gated by `updatedAt` and guarded by `isReconcileLeadClient`. Calling it from elsewhere duplicates content across the CRDT or re-applies stale snapshots. - **Add packages to `optimizeDeps`** — Vite won't pre-bundle Yjs correctly otherwise, causing runtime errors in dev. - **One `Y.Doc` per document** — Don't create multiple Y.Doc instances for the same document ID. `useCollaborativeDoc` caches by ID. - **Destroy Y.UndoManager on doc change** — Stale managers hold Y.Doc references and grow unboundedly. Recreate on `docId` change. ## Related Skills - `real-time-sync` — The change-sync system that delivers the `updatedAt` bump driving editor reconciliation; also `useReconciledState` for non-Yjs surfaces - `storing-data` — The `_collab_docs` table and SQL canonical content - `security` — `registerShareableResource`, `resolveAccess`, `assertAccess` - `self-modifying-code` — Agent edits to collaborative documents edit canonical SQL content, not raw Yjs