velt-presence-best-practices

Velt Presence Best Practices

Comprehensive implementation guide for Velt's real-time user presence and cursor tracking features. Contains 15 rules across 8 categories covering setup, configuration, data access, cursor sharing, events, UI customization, wireframe template variables, and debugging.

When to Apply

Reference these guidelines when:

• Adding user presence avatars to show who's online
• Configuring inactivity timeouts (away/offline states)
• Implementing real-time cursor tracking on canvas or page
• Subscribing to presence data or user state changes
• Filtering presence by location or document
• Customizing presence avatar UI with wireframes
• Implementing flock mode (follow me) for shared navigation sessions
• Debugging presence not showing or users appearing offline

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Core Setup	CRITICAL	core-
2	Data Access	HIGH	data-
3	Configuration	HIGH-MEDIUM	config-
4	Cursor	HIGH	cursor-
5	Events	MEDIUM	events-
6	UI Customization	MEDIUM	ui-
7	Wireframe Variables	MEDIUM	wireframe-variables-
8	Debugging	LOW-MEDIUM	debug-

Quick Reference

Core Setup (CRITICAL)

• core-auth-provider — Use authProvider on VeltProvider, never identify()
• core-setup — Add VeltPresence component for avatar display
• core-document-setup — Set document context for presence scoping

Data Access (HIGH)

• data-presence-hooks — usePresenceData, usePresenceEventCallback hooks
• data-presence-api — Vanilla JS getPresenceElement, getData, on

Configuration (HIGH-MEDIUM)

• config-inactivity-time — Away/offline timeout configuration
• config-max-users — Avatar overflow control
• config-self-visibility — Include/exclude current user
• config-location-presence — Location-based presence filtering
• config-flock-mode — Flock mode (follow me) setup, enableFlockMode, startFollowingUser/stopFollowingUser, onNavigate callback for SPA routing, defaultFlockNavigation

Cursor (HIGH)

• cursor-setup — VeltCursor for real-time cursor tracking on canvas

Events (MEDIUM)

• events-state-change — Subscribe to user online/away/offline transitions

UI Customization (MEDIUM)

• ui-wireframes — VeltPresenceWireframe customization

Wireframe Variables (MEDIUM)

• wireframe-variables-presence — Bind Presence wireframe slots via componentConfig.<path> template variables (velt-data / velt-if / velt-class)

Debugging (LOW-MEDIUM)

• debug-common-issues — Troubleshooting presence issues

How to Use

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-setup.md
rules/shared/config/config-inactivity-time.md
rules/shared/data/data-presence-hooks.md

Each rule file contains:

• Brief explanation of why it matters
• Correct code example with explanation
• Verification checklist
• Source pointers to official docs

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