Agent-Skills.md

Agent Skills: 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.

UncategorizedID: velt-js/agent-skills/velt-single-editor-mode-best-practices

Repository

velt-js/agent-skills
velt-js

Install this agent skill to your local

pnpm dlx add-skill https://github.com/velt-js/agent-skills/tree/HEAD/skills/velt-single-editor-mode-best-practices

Skill Files

Browse the full folder contents for velt-single-editor-mode-best-practices.

Download Skill

Loading file tree…

skills/velt-single-editor-mode-best-practices/SKILL.md

Skill Metadata

Name
velt-single-editor-mode-best-practices
Description
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.

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