# BcrdtCollaborativeDocument (Class)

`Bit.Bcrdt.BcrdtCollaborativeDocument` - package `Bit.Bcrdt` - implements `IAsyncDisposable`

An open collaborative document: replicated state, presence, history and connection in one object.

This is the type applications work with. It composes the pieces that a collaborative feature always needs together - the CRDT document, the presence registry, an undo stack, a sync provider and a persistence binding - so that a feature is written against one object with a coherent lifetime rather than five that have to be wired up correctly and torn down in the right order.

Every part remains directly accessible. BcrdtCollaborativeDocument.Crdt is the real document and the full engine API is available through it; nothing here hides capability, it only removes ceremony.

## Property

- **Awareness** : `BcrdtAwarenessStore` - Ephemeral state published by every participant.
- **ClientId** : `ulong` - This replica's session identity.
- **ConnectionStatus** : `BcrdtConnectionStatus` - Where the connection stands, or BcrdtConnectionStatus.Disconnected if offline-only.
- **Crdt** : `BcrdtDocument` - The underlying replicated document.
- **Id** : `string` - The document's identifier, as passed to the collaboration service.
- **IsSynced** : `bool` - Whether the document currently matches the peer's copy.
- **Map** : `BcrdtMap` - The default root map, for documents that need only one.
- **Persistence** : `BcrdtDocumentPersistence` - The persistence binding, when the document is backed by a store.
- **Presence** : `BcrdtPresenceService` - The typed view of who is here and where their cursors are.
- **Sync** : `BcrdtSyncProvider` - The synchronization provider, when the document is connected to a peer.
- **Undo** : `BcrdtUndoManager` - The default undo stack for local edits, if one was requested.
  It tracks untagged local edits - the origin application code and the built-in editing components use - to the default map (BcrdtCollaborativeDocument.Map) and to every root type obtained through this object's accessors (BcrdtCollaborativeDocument.Text, BcrdtCollaborativeDocument.Array, BcrdtCollaborativeDocument.GetMap, BcrdtCollaborativeDocument.Set). Roots obtained directly from BcrdtCollaborativeDocument.Crdt are not added; call BcrdtUndoManager.AddToScope for those. For an undo stack per editing surface, use BcrdtCollaborativeDocument.CreateUndoManager.

## Method

- **Array**(string name) : `BcrdtArray` - A named root sequence.
- **BeginTransaction**(object origin = null) : `BcrdtCollaborativeTransaction` - Batches several changes into one update and one round of events.
  Dispose the returned transaction to commit, or await BcrdtCollaborativeTransaction.CommitAsync to commit and additionally wait for the changes to reach storage.
  
  Do not hold a transaction open across an await. While it is open, every change made to the document - by another event handler that runs during the await, or by an update arriving from a peer - joins it and is published as part of this batch, with this batch's origin. A transaction opened inside another one joins it too, and committing it publishes nothing until the outer one commits.
- **ConnectAsync**(CancellationToken cancellationToken = null) : `ValueTask` - Connects to the configured peer and keeps the connection alive.
  Disconnecting withdraws the local participant from everybody's presence list. Connecting again republishes the identity last set with BcrdtPresenceService.SetUser, so the participant reappears as who they are rather than as an anonymous cursor.
- **CreateUndoManager**(params BcrdtAbstractType[] scope) : `BcrdtUndoManager` - Creates an undo stack scoped to particular types.
  Scoping matters: an undo stack over a whole document will happily undo an edit the user made in an unrelated field five minutes ago. Scope one per editing surface.
- **CreateUndoManager**(BcrdtUndoManagerOptions options, params BcrdtAbstractType[] scope) : `BcrdtUndoManager` - Creates an undo stack scoped to particular types, with explicit settings.
- **DisconnectAsync**(CancellationToken cancellationToken = null) : `ValueTask` - Disconnects and stops reconnecting, leaving the document editable offline.
- **DisposeAsync**() : `ValueTask`
  Tears down in the order that keeps the document correct for as long as possible: say goodbye to peers while still connected, so they drop this participant immediately rather than after the presence timeout; stop the network, so nothing more arrives; then flush storage, which by then holds everything that did arrive; then release the document itself. A failure in one step does not skip the others.
- **FlushAsync**() : `Task` - Waits until every pending change has reached storage.
- **GetMap**(string name) : `BcrdtMap` - A named root map.
- **Set**(string name) : `BcrdtSet` - A named root set.
- **Text**(string name) : `BcrdtText` - A named root text field.
- **ToJson**() : `SortedDictionary<string, object>` - A plain-object projection of the whole document, for inspection and tests.
- **Transact**(Action<BcrdtTransaction> action, object origin = null) : `void` - Runs a batch of changes as a single transaction.

## Event

- **Changed** : `Action<BcrdtUpdateEventArgs>` - Raised whenever anything in the document changes, locally or remotely.