real-time-collab

name	real-time-collab
description	Multi-user collaborative editing with Yjs CRDT, SSE fast-path transport, and granular server-side merge. Use when adding real-time collaborative editing to a template, debugging sync issues, or understanding how the agent and humans edit documents simultaneously.
scope	dev
metadata	{"internal":true}

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

// 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:

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.

// 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:

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:

createCollabPlugin({
  access: { mode: "resource", resourceType: "document" },
  maxPayloadBytes: 512 * 1024,
});

Enabling Collaboration

1. Install packages

pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core

2. Add collab server plugin (with explicit access)

// 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

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

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

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:

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:

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):

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:

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