Schema-driven collaborative documents, local editing, and editor bindings in TypeScript.
DocSync represents documents as CRDT token sequences. Applications supply node, attribute, mark, and child rules; the engine provides editing, identity-preserving operations, per-actor History, synchronization, and recovery primitives. The core has no external runtime dependencies. Editor bindings and Presence views are separate, optional packages.
Development status: all ten library packages are private
0.0.0workspaces, not published npm releases. Examples use a built checkout or locally packed tarballs. TypeScript is the production implementation in this repository, not a claim that every application/deployment scenario has been production-qualified.
Documentation · Getting started · Roadmap and verification · Maintainer handoff
Use Node.js 22.18 or later and npm. A modern browser is needed for the demos.
git clone https://github.com/barocss/doc-sync.git
cd doc-sync
npm ci
npm run build
npm run dev:clientFollow the URL printed by the demo. dev:client demonstrates ProseMirror, Tiptap,
Slate and Lexical in local/synchronized modes. npm run dev starts the original
HTTP/SSE demo at http://localhost:5410; npm run dev:local needs no document
server. Demos are development examples, not public deployment templates.
Save this as example.ts in the repository root after building, then run
node example.ts. The same API works in a browser bundle.
import assert from 'node:assert/strict';
import {Client} from '@barocss/doc-sync/client';
import type {Schema} from '@barocss/doc-sync';
const schema: Schema = {
root: 'document',
marks: ['bold'],
nodes: {
document: {shape: 'flow', children: ['paragraph'], default: 'paragraph'},
paragraph: {shape: 'text'},
},
};
const client = new Client({schema, actor: 'local-example'});
client.edit([{op: 'insert', at: [0, 0], content: 'Hello'}]);
const first = client.model().children?.[0]?.runs?.[0];
assert(first && 'text' in first);
assert.equal(first.text, 'Hello');
client.undo();
client.redo();
const saved = JSON.parse(JSON.stringify(client.captureState()));
const reopened = Client.fromState(saved, {schema});
assert.deepEqual(reopened.model(), client.model());
reopened.dispose();
client.dispose();edit() already applies and records the action; do not apply its returned
operations again. captureState() is an explicit local snapshot, not automatic
persistence. The application must save it successfully and manage its lifetime.
Every package README has setup, API usage, lifecycle, and support boundaries.
| Package | Use it for |
|---|---|
@barocss/doc-sync |
CRDT, Client, local/sync backends, server, schema, data, Presence |
@barocss/doc-sync-prosemirror |
ProseMirror schema conversion and binding |
@barocss/doc-sync-tiptap |
Tiptap extension using the ProseMirror binding |
@barocss/doc-sync-slate |
Slate binding and codec |
@barocss/doc-sync-lexical |
Lexical nodes, schema conversion and binding |
@barocss/doc-sync-presence-ui |
Framework-free cursor, selection, draft and avatar views |
@barocss/doc-sync-presence-react |
React Presence components and hooks |
@barocss/doc-sync-presence-vue |
Vue Presence components and composables |
@barocss/doc-sync-presence-svelte |
Svelte Presence component and store |
@barocss/doc-sync-presence-solid |
SolidJS Presence components and accessors |
There is no doc-sync-core package or core /prosemirror export. Import each
binding by its package name. For another project, use the local package recipe, not an unverified registry install command.
npm run check:packages builds, packs and installs all ten packages in isolated
local consumers; it does not publish them.
The Tiptap binding is implemented as @barocss/doc-sync-tiptap, with DocSync
and createTiptapExtensions. Start with the Tiptap guide
or its package README. Run
node apps/demo/tiptap/start.mjs after the workspace build for its two-editor demo.
It uses Tiptap 3.32.2 and the separate ProseMirror binding; its generated schema
must not be mixed with StarterKit schema/history extensions. It remains a private,
unpublished workspace, like the other bindings.
- Define the schema and use schema diagnostics/preflight before changing it. Identity and compatibility are protocol contracts, not merely UI validation.
- Create a Client. Without transport it is local;
adding
actorandtransportat construction selects synchronization. Mode cannot be switched later. Active replicas must have distinct actor IDs. - Mount an editor binding. Bindings create a host per view. Multiple views of one client share an actor and History; they are not independent collaborators.
- Implement server routing, authentication and recovery for your application. A profile, actor name or Presence message is not permission.
- Dispose bindings/subscriptions when views unmount, and dispose the client when its owner closes the document. Handle pending changes and recovery before discarding synchronized state.
- Shared maps and lists:
Client.datawithcreateDataSchema()and servercreateDataHub; data GC remains disabled. - Graphic schemas: empty/stored containers use the TypeScript engine; text bindings do not provide canvas rendering.
- Spreadsheets: experimental SparseSheet and StructuralSheet APIs are not integrated with Client/DocHub synchronization.
- Presence: ephemeral state and optional UI, separate from persistent document History. The host maps document positions to screen coordinates.
- AI and bots: private MCP/bot workspaces, bounded reads, conditional edits and owner proposals. Real-model quality, public deployment and automatic authority are not implied. See bot roadmap.
- Rust SDK: experimental native APIs with a bounded support matrix. Rust/WASM is not a selectable production Client backend.
Run from the repository root after npm ci:
| Command | What it checks or starts |
|---|---|
npm run build |
Compiled ESM and declaration outputs in dependency order |
npm run typecheck |
Workspace TypeScript (builds packages first) |
npm test |
Workspace tests, including bounded randomized scenarios |
npm run check:readmes |
Package coverage, local README links and executable root/core snippets |
npm run check:packages |
Tarballs, exports, peer dependencies and isolated consumers |
npm run docs:build |
VitePress site and generated content |
npm run docs:check |
Built documentation pages, links and English prose |
npm run docs:dev |
Local documentation development server |
See documentation maintenance for sources,
example verification and package README conventions. Generated dist files are
not source edits. Run browser checks separately when changing user interactions;
unit tests do not prove IME, accessibility or real-browser behavior.
Performance reports and past validation remain in benchmarks/results,
HANDOFF.md, and the roadmap status.
Their dates, commits and scopes matter: historical results are not new measurements.
Long-duration load testing and registry publication are separate release activities.