velt-js Velt Single Editor Mode Best Practices
Comprehensive implementation guide for Velt's Single Editor Mode in React and Next.js applications. Contains 14 rules across 7 categories, prioritized by impact to guide automated code generation and integration patterns.
When to Apply
Reference these guidelines when:
- Enabling Single Editor Mode to restrict editing to one user at a time
- Setting up VeltSingleEditorModePanel and default UI
- Calling setUserAsEditor() and handling error codes
- Subscribing to editor state via useUserEditorState or isUserEditor()
- Building custom access request UX (editor accept/reject, viewer request/cancel)
- Scoping Single Editor Mode to specific containers with singleEditorModeContainerIds()
- Controlling elements with data-velt-sync-access attributes
- Enabling auto-sync for text elements (input, textarea, contenteditable)
- Configuring editor access timeout and auto-transfer behavior
- Subscribing to SEM events (accessRequested, editorAssigned, etc.)
- Handling multi-tab editing scenarios with singleTabEditor and editCurrentTab()
- Configuring heartbeat and presence detection for editor tracking
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Core Setup | CRITICAL | core- |
| 2 | Editor State Management | CRITICAL | state- |
| 3 | Access Request Flow | HIGH | access- |
| 4 | Element Control | HIGH | elements- |
| 5 | Timeout Configuration | MEDIUM | timeout- |
| 6 | Event Handling | MEDIUM | events- |
| 7 | Debugging & Testing | LOW-MEDIUM | debug- |
Quick Reference
1. Core Setup (CRITICAL)
core-setup— Enable Single Editor Mode with config, default UI, and panel component
2. Editor State Management (CRITICAL)
state-hooks— Use useUserEditorState and useEditor hooks for React editor statestate-set-user-editor— Call setUserAsEditor() with error handling for all 3 error codesstate-editor-api— Subscribe to isUserEditor() and getEditor() Observables
3. Access Request Flow (HIGH)
access-hooks— Use useEditorAccessRequestHandler hook for React access flowaccess-editor-side— Handle incoming requests with accept/reject via APIaccess-viewer-side— Request and cancel editor access as viewer
4. Element Control (HIGH)
elements-container-scope— Scope SEM to specific containers and enable auto-syncelements-sync-attributes— Apply data-velt-sync-access attributes to native HTML elements only
5. Timeout Configuration (MEDIUM)
timeout-hooks— Use useEditorAccessTimer for React countdown UItimeout-config— Configure timeout duration and auto-transfer behavior
6. Event Handling (MEDIUM)
events-hooks— Use useLiveStateSyncEventCallback for React event subscriptionsevents-subscribe— Subscribe to all 7 SEM event types via API
7. Debugging & Testing (LOW-MEDIUM)
debug-common-issues— Common issues, heartbeat config, and testing checklist
How to Use
Read individual rule files for detailed explanations and code examples:
rules/shared/core/core-setup.md
rules/shared/state/state-set-user-editor.md
rules/react/access/access-hooks.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Source pointers to official documentation
Compiled Documents
AGENTS.md— Compressed index of all rules with file paths (start here)AGENTS.full.md— Full verbose guide with all rules expanded inline