> )}
>
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> const offStatus = manager.onStatusChange((status) => {
> document.querySelector('#status')!.textContent = status;
> });
> const offSynced = manager.onSynced((synced) => {
> document.querySelector('#synced')!.textContent = synced ? 'Yes' : 'No';
> });
> const offRemote = manager.onRemoteSelectionsChange((selections) => {
> console.log('Remote cursor, selection, and highlight state:', selections);
> });
> ```
Ace cursor and selection events are published automatically after attachment, and awareness changes trigger remote marker rendering. Custom UI can publish explicitly:
```ts theme={null}
manager.publishCurrentSelection('cursor');
manager.publishCurrentSelection('selection');
manager.addHighlight({
start: { row: 0, column: 0 },
end: { row: 0, column: 10 },
}, '#f59e0b');
```
Cursor, selection, and highlight awareness is ephemeral. It is not part of the shared file or a saved version.
### Step 7: Initial Content and Force Reset
Initial content is plain text and is applied only when the shared text is new and uninitialized:
```ts theme={null}
const initialContent = [
'function add(a, b) {',
' return a + b;',
'}',
].join('\n');
```
Use a reset only for an explicit destructive action:
```ts theme={null}
await manager.forceReset('// Reset file\n');
```
> [!WARNING]
>
> `forceResetInitialContent` and `forceReset()` replace the shared file for every collaborator.
### Step 8: Work with Shared Text
```ts theme={null}
const currentValue = manager.getValue();
manager.setValue('const answer = 42;', 'toolbar-set');
manager.insertText(' // note');
manager.flushEditorToStore('manual-save');
```
`insertText()` accepts an optional character index. Without one, the manager uses the current Ace cursor when available.
### Step 9: Configure Collaborative Undo and Redo
The manager creates one Yjs `UndoManager` for the shared text.
> [tab] React / Next.js
>
> ```tsx theme={null}
>
>
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> const undoManager = manager.getUndoManager();
>
> undoManager?.undo();
> manager.flushEditorToStore('undo');
>
> undoManager?.redo();
> manager.flushEditorToStore('redo');
> ```
Use these controls as the user-facing collaborative history. Mixing Ace's local history commands with Yjs undo can produce a history that does not match the shared document.
### Step 10: Save and Restore Versions
```ts theme={null}
const versionId = await manager.saveVersion('Before refactor');
const versions = await manager.getVersions();
await manager.restoreVersion(versionId);
```
Saving flushes Ace before the checkpoint. Restoring updates the Store and reapplies the shared text to Ace.
### Step 11: Subscribe to CRDT Events
> [tab] React / Next.js
>
> ```tsx theme={null}
> import { useVeltClient } from '@veltdev/react';
>
> const { client } = useVeltClient();
>
> useEffect(() => {
> if (!client) return;
> const subscription = client.getCrdtElement()
> .on('updateData')
> .subscribe((event) => console.log('CRDT update:', event));
> return () => subscription.unsubscribe();
> }, [client]);
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> const crdtSubscription = client.getCrdtElement()
> .on('updateData')
> .subscribe((event) => console.log('CRDT update:', event));
> ```
### Step 12: Attach or Replace an Editor (Alternative)
Use the attach-later lifecycle only when the Store must initialize before Ace:
> [tab] React / Next.js
>
> ```tsx theme={null}
> const collaboration = useCollaboration({
> editorId: 'shared-code-file',
> initializeWithoutEditor: true,
> rangeFactory,
> });
>
> collaboration.attachEditor(editor, { rangeFactory });
> collaboration.detachEditor();
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> const manager = await createCollaboration({
> editorId: DOCUMENT_ID,
> veltClient: client,
> rangeFactory,
> });
>
> manager.attachEditor(editor, { rangeFactory });
> manager.detachEditor();
> ```
This replaces passing `editor` to `createCollaboration()`. Do not use both paths in one initialization flow.
### Step 13: Custom Encryption (Optional)
> [tab] React / Next.js
>
> ```tsx theme={null}
> apiKey="YOUR_VELT_API_KEY"
> authProvider={authProvider}
> encryptionProvider={encryptionProvider}
> >
>
>
> ```
> [tab] Other Frameworks
>
> ```ts theme={null}
> client.setEncryptionProvider(encryptionProvider);
> ```
See [setEncryptionProvider()](https://velt.dev/docs/api-reference/sdk/api/api-methods.md#setencryptionprovider-encryptionprovider) and [VeltEncryptionProvider](https://velt.dev/docs/api-reference/sdk/models/data-models.md#veltencryptionprovider).
### Step 14: Clean Up
> [tab] React / Next.js
>
> `useCollaboration()` and `AceCrdtEditor` unsubscribe and destroy their collaboration manager on unmount. When an app owns the Ace instance, use an explicit manager-first cleanup before destroying Ace:
>
> ```tsx theme={null}
> useEffect(() => {
> return () => {
> collaboration.destroy();
> editor.destroy();
> editor.container.remove();
> };
> }, [collaboration.destroy, editor]);
> ```
>
> The hook's later unmount cleanup is idempotent, so the explicit `destroy()` safely preserves the required order.
> [tab] Other Frameworks
>
> Unsubscribe first, destroy collaboration so it releases Ace listeners and markers, then destroy Ace and remove its DOM:
>
> ```ts theme={null}
> offStatus();
> offSynced();
> offRemote();
> crdtSubscription.unsubscribe();
> manager.destroy();
> editor.destroy();
> editor.container.remove();
> ```
## Notes
* **Plain-text model**: Ace modes and themes are local presentation; only text is stored in `Y.Text`.
* **One binding**: Passing `editor` to the factory attaches it automatically.
* **Range factory**: Use Ace's verified `Range` constructor for remote markers.
* **Automatic selections**: The manager attaches Ace selection listeners and publishes cursor/selection state through awareness.
* **Advanced escape hatches**: `getDoc()`, `getYText()`, `getProvider()`, `getAwareness()`, and `getUndoManager()` are for diagnostics or advanced integrations. `getText()` and `getYText()` return the same shared `Y.Text`; internally, `getYText()` delegates to `getText()`. Do not create a second Y.Doc, provider, or shared text.
* **Production authentication**: Use a server-backed React `authProvider` and never expose privileged server tokens in browser code.
## Testing and Debugging
1. Open the same Velt document and Ace `editorId` as two different authenticated users in separate browser profiles.
2. Type and delete concurrently at different positions.
3. Verify visible cursor carets, selected ranges, attention highlights, Yjs undo/redo, versions, reconnect behavior, and persistence.
4. Repeat with the production mode, theme, worker, and bundler configuration.
Common issues:
* Mode or theme is missing: import the matching `ace-builds/src-noconflict` module before creating Ace.
* Text does not sync: remove React `value`/`defaultValue` and confirm both clients use the same IDs.
* Markers do not appear: provide `cursorData`, the complete `rangeFactory`, a sized host, and marker CSS.
* Duplicate Yjs warning: deduplicate `yjs` and `@veltdev/crdt` in the application bundle.
> [!TIP]
>
> Use the [VeltCrdtStoreMap debugging interface](https://velt.dev/docs/realtime-collaboration/crdt/setup/core.md#veltcrdtstoremap) to inspect shared text and provider status.
## Complete Example
> [tab] React / Next.js
>
> ```tsx Complete App.tsx expandable lines theme={null}
> import { useEffect, useMemo, useState } from 'react';
> import ace from 'ace-builds/src-noconflict/ace';
> import 'ace-builds/src-noconflict/mode-typescript';
> import 'ace-builds/src-noconflict/theme-textmate';
> import {
> VeltProvider,
> useCurrentUser,
> useSetDocuments,
> } from '@veltdev/react';
> import { AceCrdtEditor } from '@veltdev/ace-crdt-react';
> import './styles.css';
>
> const DOCUMENT_ID = 'shared-code-file';
> const USER = {
> userId: 'ada',
> organizationId: 'my-org-id',
> name: 'Ada Lovelace',
> email: 'ada@example.com',
> };
> const Range = ace.require('ace/range').Range;
>
> function CollaborativeEditor() {
> const user = useCurrentUser();
> const { setDocuments } = useSetDocuments();
> const [documentReady, setDocumentReady] = useState(false);
>
> useEffect(() => {
> if (!user) return;
> setDocuments([{
> id: DOCUMENT_ID,
> metadata: { documentName: 'Shared Ace file' },
> }]);
> setDocumentReady(true);
> }, [user, setDocuments]);
>
> if (!user || !documentReady) return