# Velt Single Editor Mode Best Practices

> Velt Single Editor Mode implementation patterns and best practices for React, Next.js, and web applications. Use when implementing exclusive editing access, editor/viewer role management, access request handoff flows, element-level sync control, timeout-based editor transfer, or multi-tab editing restrictions.

- Skill: `velt-js/velt-single-editor-mode-best-practices` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add velt-js/velt-single-editor-mode-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/velt-js/velt-single-editor-mode-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: velt-js (https://skillmd.com/u/velt-js)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/velt-js/velt-single-editor-mode-best-practices

---


# 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 state
- `state-set-user-editor` — Call setUserAsEditor() with error handling for all 3 error codes
- `state-editor-api` — Subscribe to isUserEditor() and getEditor() Observables

### 3. Access Request Flow (HIGH)

- `access-hooks` — Use useEditorAccessRequestHandler hook for React access flow
- `access-editor-side` — Handle incoming requests with accept/reject via API
- `access-viewer-side` — Request and cancel editor access as viewer

### 4. Element Control (HIGH)

- `elements-container-scope` — Scope SEM to specific containers and enable auto-sync
- `elements-sync-attributes` — Apply data-velt-sync-access attributes to native HTML elements only

### 5. Timeout Configuration (MEDIUM)

- `timeout-hooks` — Use useEditorAccessTimer for React countdown UI
- `timeout-config` — Configure timeout duration and auto-transfer behavior

### 6. Event Handling (MEDIUM)

- `events-hooks` — Use useLiveStateSyncEventCallback for React event subscriptions
- `events-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