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.
76%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.agents/skills/real-time-collab/SKILL.mdCollaborative 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.
Y.Doc stores the document as a Y.XmlFragment (ProseMirror node tree)ySyncPlugin/_agent-native/poll-events EventSource delivers collab
events push-style; while SSE is healthy the collab poll interval relaxes to
~12 s/_agent-native/poll is polled every 2 s when SSE
drops mid-session. On serverless, /events answers 204 up front (poll-live)
and this client relaxes to ~12 s, because /poll is the only channel.acquireCollabPollBoost() and the shared transport polls every 2.5 s
whenever no stream is connected: a no-op while SSE or the hosted gateway is
live. A joiner is noticed on the existing user's next ~12 s collab poll
(the joiner sees them at once), a leaver within one poll plus the 30 s
awareness TTL. The boost lapses after 3 minutes with no input and no remote
events. Lone tabs pay nothing extra. Events under the request source a
connection posts with (any app-chosen tab id, not only getBrowserTabId())
are this tab's own and never count. A read-only viewer must join the doc too (Design's
useViewerPresence; it never uses the ydoc), or it never sees an editor
and stays on the idle cadence. A viewer on a different screen than the
editor shares no doc with them; its own collab poll sees the design's
resource-scoped events from other tabs and starts the boost (60 s) itself.Y.mergeUpdates before sending; flushed immediately on
visibilitychange / pagehide_collab_docs table persists Yjs state as base64 in Postgres. Tombstone
compaction fires automatically when the stored blob
exceeds 4× the fresh encoded size.POST /_agent-native/collab/:docId/updateupdatedAt → change-sync refetch → the open editor reconciles the new content into the live Y.Doc (see below) → poll update → all clientsBoth 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.
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.
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 → ignoreWithout 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.
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.
A lead that sees another visible human waits PEER_SETTLE_MS (2.5 s) before
adopting a newer snapshot, so that peer's in-flight typing lands first. The wait
is skipped only when the host passes isEditorClean(liveMarkdown) to
useCollabReconcile, it returns true, and the live doc still equals the last
authoritative snapshot the hook adopted. Do not substitute
lastAppliedSerialized: local emits update it, so it cannot say whether the
doc holds unsaved text. Content's isEditorClean also requires no queued or
in-flight save, no reconcile recovery draft, and no journaled draft that
differs from the live doc.
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.
Inspect the schema and sharing registration before configuring collaboration:
mode: "resource" and the resource type
registered through registerShareableResource.mode: "all-authenticated".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.
Write routes reject payloads exceeding maxPayloadBytes (default 2 MB) with
HTTP 413. Override:
createCollabPlugin({
access: { mode: "resource", resourceType: "document" },
maxPayloadBytes: 512 * 1024,
});pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core// 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" },
});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),
},
});Pass localCopy: { onEditsDisplaced } to keep each doc's acknowledged state
in IndexedDB, per account. A doc opened again is ready from that copy at once
(fromLocalCopy: true, isSynced: false), and the hook asks the server only
for what the copy lacks. The server answers with its state vector; if it does
not cover the copy, or its answer cannot be read or applied, the copy is
thrown away and the doc reopens from the server (the hook's ydoc changes). Copies are cleared on sign-out and when a
different account uses the browser, and are bounded (least recently opened go
first). Storage that cannot be used just means no copy.
The doc takes edits from the copy straight away, but sends them only once the
server's vector covers the copy. Typing the server's state leaves out (the
copy was thrown away, the server deleted the block it went into, or the doc is
gone) is passed to onEditsDisplaced as { state, reason }, where state is
the whole doc as it stood with the typing. None of it is sent, then or by the
next open. Keep it where the user can find it (Content files it in Version
History for the page's owner, and as a private page in their own space for
anyone else), and never apply it back to the doc: the server's deletions stand.
Server actions file under whoever is signed in, so keep it for the account and
org that typed it: stop when the editor closes or the session changes.
subscribeSessionInvalidation(listener) from @agent-native/core/client/hooks
hears a sign-out or organization switch, in this tab or another, as it starts.
A copy is a cache of the server's doc, never a second source: it is saved only
while none of the tab's edits are unacknowledged, so it never holds text the
server lacks. Treat fromLocalCopy as "drawn, not yet caught up": don't seed
an empty doc or decide anything about the stored body from it.
To start that read with the page instead of after the editor mounts, call
prefetchCollabState(docId) from
@agent-native/core/client/collab/prefetch (it doesn't load the collab
client). The hook takes the answer over when it opens the same doc within a few
seconds, for the account the copy belongs to. A read made before the tab's
session is known belongs to the first session read; it is dropped once the
session changes, or a sign-out or organization switch starts in this tab or
another.
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
});optimizeDeps: {
include: [
"yjs",
"y-protocols/awareness",
"@tiptap/core",
"@tiptap/extension-collaboration",
"@tiptap/extension-collaboration-caret",
"@tiptap/y-tiptap",
],
}| Route | Purpose |
|---|---|
GET /_agent-native/collab/:docId/state | Fetch full Y.Doc state (accepts ?stateVector= for diff, and then also returns the server's stateVector) |
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 |
A live copy is a document whose Yjs state is the only writable copy of a body;
the server derives its text on every commit. Declare one with defineLiveCopy
from @agent-native/core/collab and pass it to createCollabPlugin({ liveCopy, autoSeed: false }). Its name is its identity: defining the same name again
replaces the old binding, so a dev reload never leaves a stale one in front;
work the old binding started commits nothing unless its transaction was
already committing. Then:
createBoundedTaskRunner, never on the request thread. Writes to
one document wait their turn ahead of that runner, so the binding's
maxWaitingWrites (default 16), not the runner's queue, bounds them; past
it a write fails with build_failed / queue_full, a 503. Readers of a
row this instance has not cached share one runner task, and its text is
cached with it, so readLiveCopy of a cached row runs none. Its module
exports tasks = defineLiveCopyTasks({ derive, seed, edits }) from
@agent-native/core/collab/live-copy-tasks and is imported as
./tasks.ts?bounded-task, which the app's Vite build, server build and
@agent-native/core/vitest-config already resolve; declare that module
pattern's default export as a BoundedTaskSource in the app's *.d.ts. A
handler returns { kind: "refused", reason } for content it cannot
represent; never drop it.mutateLiveCopy(binding, docId, { edit, input }),
where edit names one of the module's edits, and seed with seedLiveCopy.
Other write helpers throw write_refused for covered documents, and
getDoc, getText and getJson throw read_refused; read with
readLiveCopy. Do not work around either. All three throw not_live_copy
for a document the binding does not cover, and for a binding that was
released or replaced; call them with the binding defineLiveCopy returned
last. Only the first means the document left its live copy; the second has
reason binding_inactive, and retrying with the same handle cannot succeed. Call these writers, and applyUpdate on a live copy, outside any
transaction; they refuse a caller's, including a persist hook's, so a hook
reads its own document with getState or readLiveCopy but never writes
it. Rows that must commit with one edit
(say, the suggestion it accepts) go in mutateLiveCopy's persist option,
which runs in the edit's own transaction. On a changed edit, core stops an
attempt a peer overtook before that persist runs, so a persist that checks
the app's rows against the edit sees the edit's own base. That check is
exact only when the binding's persist takes the lock every commit of the
document shares, such as the page row. An edit that changes nothing commits
no row core can check first: lock the app's rows, compare
loadYDocVersion(docId) with change.version, and return without writing
when it moved; core then redoes the edit. A persist's error is never retried.persist hook, which runs in the
commit transaction before _collab_docs. Do not save derived text elsewhere.
Return { derived: false, reason } when it leaves them alone: the Yjs state
still commits, and the update ack says liveCopy: "not_derived", so the
client can resume its own saves. An ack without liveCopy means unknown.LiveCopyError by code. Absent, unseeded and malformed_state are
different states; never treat malformed state as empty. Only an empty field
is unseeded, so an update or edit that would empty it is refused; editors
keep one empty block instead.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.
The agent is a visible collaborator, not a silent content-swapper. Core handles most of this automatically:
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.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"}._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.
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.
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.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.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.flushUpdates() from
useCollaborativeDoc before the save; false means delivery failed, so retry
later instead of saving. Build the saved value from the live document at that
moment, not from a snapshot taken at the last keystroke.requestInitialSeed (backed by seedXmlFragmentIfEmpty) so the server seeds
once and every editor adopts that copy.optimizeDeps — Vite won't pre-bundle Yjs correctly
otherwise, causing runtime errors in dev.Y.Doc per document — Don't create multiple Y.Doc instances for the
same document ID. useCollaborativeDoc caches by ID.docId change.real-time-sync — The change-sync system that delivers the updatedAt bump
driving editor reconciliation; also useReconciledState for non-Yjs surfacesstoring-data — The _collab_docs table and SQL canonical contentsecurity — registerShareableResource, resolveAccess, assertAccessself-modifying-code — Agent edits to collaborative documents edit canonical
SQL content, not raw YjsBuilderIO/agent-native
cf9ff10
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.