Public API
Ten packages provide the dependency-free Core, four editor bindings and five optional Presence UI packages. All remain private before registry release. The demo, documentation, and benchmark workspaces are private. See packages and engines for independent imports and peer dependencies.
Entry points
| Import | Main exports |
|---|---|
@barocss/doc-sync | Client, LocalClientState, Doc, History, commands, model/schema/position helpers, createGraphicHelpers, SpreadsheetSchema, SparseSheet, StructuralSheet, and shared types. |
@barocss/doc-sync/client | Client, createEditorHost, BindingClient, client options and types. |
@barocss/doc-sync/sync | SyncClient, HttpTransport, typescriptClientEngineFactory, ClientEngineFactory, upgradeOpenEditorSchema, OpenEditorSchemaHost, ModelRange, protocol constants and types. |
@barocss/doc-sync/node | NodeHttpTransport, NodeHttpTransportOptions for Node.js HTTP and SSE synchronization. |
@barocss/doc-sync/editor | Editor host contracts, inspectEditorSchema, inspectSpreadsheetSchema and capability declarations. |
@barocss/doc-sync/server | DocHub, HubOptions, createDataHub, DataHubOptions. |
@barocss/doc-sync/data | SharedMap, SharedList, createDataSchema, SharedData and value/ID/local validator types; access through Client.data. |
@barocss/doc-sync/presence | createPresenceStore, connectClientPresence, validated state/target/draft types. |
@barocss/doc-sync-presence-ui | mountPresence, createPresenceProjector, clipping and projection types. |
@barocss/doc-sync-presence-react | PresenceProvider, PresenceOverlay, primitive components, usePresence. |
@barocss/doc-sync-presence-vue | PresenceProvider, PresenceOverlay, primitive components, usePresence. |
@barocss/doc-sync-presence-svelte | PresenceOverlay, presenceReadable. |
@barocss/doc-sync-presence-solid | PresenceProvider, PresenceOverlay, named layers, createPresence/usePresence, usePresenceStore. |
@barocss/doc-sync-prosemirror | PmBinding, buildPmSchema, model/position conversion. |
@barocss/doc-sync-tiptap | DocSync, createTiptapExtensions, Tiptap options and storage types. |
@barocss/doc-sync-slate | SlateBinding, schema codecs and selection conversion. |
@barocss/doc-sync-lexical | LexicalBinding, buildLexicalSchema, schema nodes and selection conversion. |
The core entry points and independent binding packages form the public API. Current package exports resolve compiled ESM JavaScript and declarations. Local tarball installation is verified; registry publication and release policy remain separate gates.
Shared Map/List data
Construct the existing Client with createDataSchema and access client.data. Core /data supplies collection handles/types and a fixed internal encoding. There is no separate data Client, connection or History. Map keys merge independently; List entries retain opaque IDs through moves. Values are finite scalars or explicit same-client collection handles. Strings remain atomic. Business validation is optional and local. Authoritative application policy and complete schema-independent storage remain roadmap work. Use createDataHub for intrinsic pre-application data admission; plain DocHub remains generic. Guarded data GC is disabled until identity-aware compaction exists. See Shared maps and lists.
Presence components
The framework-free store has stable immutable snapshots and explicit expiry. The bridge carries validated state through an existing ephemeral metadata namespace, preserving editor anchors and document History. UI packages only subscribe and project positions. Framework unmount disposes its view without disconnecting the client. See Presence components for lifecycle, projection and framework examples.
Schema domains
The root package exports Schema, DocumentSchema, GraphicSchema, ContainerSpec, OrderedSpec, and SchemaDomain as types. Schema remains the shared input type accepted by Doc, Client, and DocHub. An omitted domain means document. Explicit document markers have the same fingerprint as equivalent legacy definitions. Graphic schemas require domain: 'graphic' and a container root. checkSchema enforces the domain and child rules; containers have no default or childRules and can stay empty.
container is a stored object collection. group remains a computed document list wrapper. Nested flow text boxes retain default paragraphs and document list behavior inside a graphic schema. Graphic root attributes are currently unsupported and rejected; put editable properties on stored objects.
Schema compatibility permits append-only child additions under containers but rejects changing document/graphic domains. /sync exports CONTAINER_CAPABILITY (containers-v1), required in addition to the unchanged document capability set for graphic synchronization. See the domain guide.
Custom schema preflight and sheets
createGraphicHelpers(schema) binds Doc-level object IDs and edits to a custom container/text/atom graphic descriptor. /editor preflight functions report missing or opaque view handling; they do not register renderers.
createSpreadsheetSchema, assertSpreadsheetSchema, spreadsheetSchemaVersion, DEFAULT_SPREADSHEET_SCHEMA and SparseSheet are experimental root exports. Custom sheets validate scalar fields and bind operations/checkpoints to the descriptor identity. They do not use tree Schema, Client, DocHub or the public sync wire. Read custom schema recipes.
Stable-axis spreadsheet
StructuralSheet is an experimental standalone TypeScript API. It exposes visible rows/columns, ID/index mapping, ID-based cell reads/writes, row/column insert/delete/move, shared local History, exact pending-prefix acknowledgement and replay-validated state. AxisId, AxisSpan, AxisAction and structural operation/state types are exported from the root. Numeric move destinations refer to the remaining axis after removing the target range.
receive(ops, {requireKnownReferences: true}) requires known causal sources for fresh operations. Use it consistently from server creation; it does not retroactively revalidate unresolved duplicates previously admitted in default mode. See the structural contract.
Client
Core /client exports Client, BindingClient, ClientOptions, createEditorHost, clientOwner, isBindingClient and ClientNotificationError. ActorProfile, ResolvedActorProfile, and ProfileJSON are exported from the root, /client, /local, and /sync; /sync also exports PresenceInput. Client is also exported at the Core root and its /client entry. BindingClient is Client | LocalClient | SyncClient.
new Client({schema, actor?, profile?, transport?, syncOptions?}) fixes the mode at construction. No transport creates only a LocalClient. A transport requires an actor and selects the existing SyncClient. edit(edits, record?) applies and records once; sync mode also queues the exact operations. Do not commit its return value again. model() returns a borrowed immutable model. snapshot() returns detached retained document storage, including pending edits, without History/recovery proof; read notifications may use it.
Common methods cover History, anchors, selections, observers, status, connection and presence. The lazy client.data namespace supplies root/createMap/createList/getMap/getList for the exact data Schema; other schemas reject access without conversion. ClientOptions.data.validate supplies optional local policy. Client.fromState accepts the same data option; callbacks are not saved. Local status remains offline/unsynchronized and presence empty. client.sync is null locally and is the actual SyncClient in sync mode. Use it for advanced conditional editing, recovery and schema transition APIs. The client supplies local capture/open values but writes no storage and adds no live mode conversion or Rust/WASM backend. See the Client guide for complete usage, disposal and limits. actor stays the replica ID; the optional read-only profile supplies display name, color, avatar, userId, human/bot kind and JSON metadata. Profiles do not grant authority or enter saved document/History state. See participant profiles.
Memory-only client
@barocss/doc-sync/local exports LocalClient, LocalEditorHost, createLocalEditorHost, and their option, session, observer and error types. new LocalClient({schema, actor?, profile?}) owns a production TS engine without a transport. edit applies and records once; low-level apply/commit split those steps. Selection anchors, history, composition and origin-filtered subscriptions share the editor host contract. LocalClient and Client(local) expose captureState() and fromState(unknown, {schema}), preserving actor/IDs/clock/History in a detached versioned JSON envelope. Capture rejects pending operations and active drafts. Restoration validates a new client before returning it. The caller supplies storage and owns replacement of native views; server attachment remains separate. See save and open locally. See local editing for complete usage and limits.
Editor host
@barocss/doc-sync/editor exports EditorHost, EditorSession, and createSyncClientEditorHost(client). The adapter uses the selected production SyncClient engine and its input sessions. The TypeScript implementation keeps ordinary single-text edits on an incremental path. Model values are borrowed immutable views with generation/revision stamps.
The independent binding packages export PmHostBinding, SlateHostBinding, and LexicalHostBinding. Client constructors accept Client, LocalClient or SyncClient and preserve .client. Raw SyncClient keeps its legacy path; Lexical preserves its original .input session in that path. Tiptap uses the shared PM implementation. See host integration for examples. Only the TypeScript production factory ships; a Rust/WASM adapter is not selectable.
OpenEditorSchemaHost below is the application-owned native editor rebuild lifecycle. It is separate from the backend-facing EditorHost interface.
Production engine and client state
The client in this section is SyncClient. Access it as client.sync when using the unified Client. Its server recovery envelopes differ from the local save/open format.
@barocss/doc-sync/engine exports ClientEngineFactory, ClientEngine, EngineEditingView, EngineInputSession, and typescriptClientEngineFactory. Pass the factory as new SyncClient(actor, transport, {schema, engineFactory}). Omit it for the TypeScript default. The constructor validates methods, identity, schema, version, and capabilities before connection. client.engine owns the authoritative state. The common port exposes no Doc or History objects.
| Member | Contract |
|---|---|
engine.apply(edits) | Compile and apply local edits; return exact wire operations without History or transport queuing. |
client.commit(ops, record?) | Record once and queue already-applied operations. |
engine.createSession() | Create an engine-owned composition draft. Publication applies its retained operations; InputSession commits once. |
client.disconnect() | Stop transport and retain pending changes and History. |
client.dispose() | End the client; reject protected work, unresolved conditional work, or undo/redo History. |
client.checkpoint() / restoreCheckpoint(value, epoch) | Exact legacy format-1 TypeScript snapshot/History envelope. |
client.captureState() / restoreState(value, epoch) | Format-2 client envelope with one tagged opaque engine payload and transport metadata. Restore requires matching engine/version/actor/schema and external epoch/GC proof. |
Format 2 does not convert between engines. LiveRecovery and the Node journal still use the TypeScript-specific format-1 recovery path; a portable durable adapter is future D4 work. A checkpoint capture does not persist durable state.
Legacy client.doc, client.history, and InputSession.doc return the real TypeScript objects through an optional compatibility extension. Custom Doc input sessions and document facades have a separate TypeScript adapter. A portable backend can reject those accesses. The older immutable DocumentEngine / typescriptEngine API is separate and cannot serve as ClientEngineFactory. Only TypeScript ships. Live engine switching and Rust/WASM selection are not available. Selected-engine routing and regression checks pass; broader end-to-end Chrome latency acceptance remains open. See status and limits.
Doc
| Member | Contract |
|---|---|
new Doc(actor, schema) | Create a replica with an actor-local clock and schema. |
edit(edits, options?) | Apply ordered model edits and return {ops, normalize}. |
check(ops) | Validate references and schema compatibility before application. |
apply(op) | Apply one wire operation in valid causal order. |
toJSON() | Read a canonical model whose containers can be changed by the caller. |
snapshot() | Export stored CRDT state. |
Doc.fromSnapshot(actor, snapshot, schema) | Restore a replica with a selected local actor. |
version | Revision that changes after application and compaction. |
blocks(line?), visible(line) | Read stored-line blocks and current visibility. |
compact(frontier, seqOf) | Compact stable tombstones at the agreed GC boundary. |
Model and positions
NodeJSON, Run, EditOp, and ModelPath describe editor-visible content. Op, Ticket, Item, and Snapshot describe stored and transmitted state. A model path is a current address; a token key is a stable identity. Stored group paths use canonical attribute values, including validated defaults, when grouping adjacent blocks. Model-only required-group fallbacks are not stored edit targets.
canonical, applyEdits, and diffModels normalize, apply, and compare models. pathAt, anchorAt, posOfPath, and pathOfPos convert between editor paths and token positions.
Commands and history
commands includes insertText, splitBlock, backspace, deleteForward, setMark, setLink, setBlockType, insertBlock, insertInline, insertAxis, deleteAxis, setSpan, and related attribute helpers.
The schema-driven block operations guide includes executable examples for lists, nested flows, tables, spans, inline nodes, attributes, and atomic blocks.
SyncClient owns collaboration history for connected editors. client.undo() and client.redo() create new wire operations. They do not restore a past whole-document snapshot. The exact ownership and concurrent-write rules are in collaboration intent.
Schema transitions
schemaVersion(schema) returns the fingerprint of a schema. assertCompatibleSchema(previous, next) rejects unsupported changes. After the server accepts a compatible schema, client.upgradeSchema(next) installs it locally; call client.connect() to reconnect. This does not rebuild a native editor.
Use upgradeOpenEditorSchema(client, next, host, timeoutMs?) when an editor is mounted. The application-owned OpenEditorSchemaHost blocks input, captures a ModelRange, builds and installs the replacement editor, and resumes input. The helper retains the client, its history and pending changes, anchors the selection and waits for a verified connection. The default reconnect timeout is 10 seconds. See change an open editor's schema for lifecycle steps, examples for the three editors and failure handling.
The private MCP app exposes schema inspection, compatible transitions and conditional edits to a headless participant. See the separate AI and bots section and document server connection guide.
Partial reads and Node credentials
Core exports readDocumentSlice, SliceQuery, DocumentSlice, and SLICE_LIMITS. A slice reads selected canonical children without a full toJSON() call. The first containing-line index can scan all siblings; nested and global projections can cost more. Node, UTF-16, depth, and JSON-byte budgets reject oversized pages. Covered table-cell content remains in the canonical model. Ambiguous raw/canonical grouping and model-only minimum fallbacks are rejected. See bounded reads for paths, cursor scope, and the different Core/session/MCP byte counters.
new NodeHttpTransport(doc, actor, origin, {headers}) supplies configured headers to document requests. Credentialed origins must be absolute HTTP(S) URLs with no user information, query, or fragment. Redirects are rejected. Headerless relative bases remain available for browser transport compatibility. The private hosted MCP service requires a stricter upstream origin with no path; it never forwards the incoming MCP bearer token.