> ## Documentation Index
> Fetch the complete documentation index at: https://stratasync.blode.md/llms.txt
> Use this file to discover all available pages before exploring further.

# @stratasync/y-doc

Manages Y.Doc instances for collaborative text editing, handles the Yjs sync protocol, and tracks presence per document.

## What it provides

- **YjsDocumentManager**: manages Y.Doc instances per entity field, handles sync protocol messages, tracks connection state, and derives text content from CRDT state
- **YjsPresenceManager**: tracks viewing/editing presence per document, signals focus/blur to the server, and receives session state updates
- **Message types**: typed client and server messages for the Yjs sync protocol, presence signaling, and error handling
- **Utility functions**: `DocumentKey` serialization helpers and message type guards

## Installation

```bash
npm install @stratasync/y-doc yjs
```

`yjs` is a peer dependency, so install it alongside `@stratasync/y-doc`.

## Package exports

The root barrel re-exports the managers, persistence helpers, public types from `types.ts`, and the type guards.

```ts
import {
  YjsDocumentManager,
  YjsPresenceManager,
  clearPersistedYjsDocuments,
  createPersistedYjsPrefix,
  toDocumentKeyString,
  fromDocumentKeyString,
  isYjsSyncStep2Message,
  isYjsUpdateMessage,
  isSessionStateMessage,
  isLiveEditingErrorMessage,
} from "@stratasync/y-doc";

import type {
  ConnectOptions,
  DocumentConnectionState,
  DocumentKey,
  DocViewMessage,
  DocFocusMessage,
  LiveEditingErrorCode,
  LiveEditingErrorMessage,
  SessionParticipant,
  SessionState,
  YjsDocumentManagerConfig,
  YjsTransport,
  ClientMessage,
  ServerMessage,
  YjsTransportConnectionState,
  YjsSyncStep1Message,
  YjsSyncStep2Message,
  YjsUpdateMessage,
  YjsUpdateToServerMessage,
} from "@stratasync/y-doc";
```

## Core concepts

### DocumentKey

A triple identifying a collaborative field: entity type, entity ID, and field name.

```ts
interface DocumentKey {
  entityType: string; // Model name, such as "Task"
  entityId: string; // Model instance ID
  fieldName: string; // Field name, such as "description"
}
```

Use `toDocumentKeyString` and `fromDocumentKeyString` to convert between `DocumentKey` objects and their string form (`"Task:abc-123:description"`).

### Yjs sync protocol

Two-step sync:

1. **SyncStep1**: the client sends its state vector to the server
2. **SyncStep2**: the server responds with the diff (missing updates)
3. **Updates**: after sync, incremental updates flow bidirectionally

All Yjs data is binary-encoded (`Uint8Array`) and transmitted as base64 strings within JSON messages.

### Transport layer

Both managers need a `YjsTransport` to send and receive messages:

```ts
interface YjsTransport {
  send(message: ClientMessage): void;
  onMessage(callback: (message: ServerMessage) => void): () => void;
  isConnected(): boolean;
}
```

`@stratasync/transport-graphql` provides `YjsTransportAdapter`, which bridges the Yjs protocol over the existing WebSocket connection.

## Architecture role

Sits between `@stratasync/core` and higher-level packages.

```
sync-core
  ^-- sync-y-doc
        ^-- sync-transport-graphql (provides YjsTransportAdapter)
        ^-- sync-react (useYjsDocument, useYjsPresence hooks)
```

Framework-agnostic: no React or browser dependencies beyond `yjs`.