Concepts

Key concepts to understand when working with Pulse.

Environments

An environment is an isolated workspace. Think of it like a separate database — data in one environment is completely invisible to another.

Typical setup:

• Production environment — your live site
• Staging environment — for testing before release

Each environment has its own:

• API key pair (pk_ + sk_)
• Users, rooms, threads, comments
• Complete data isolation

You create and manage environments from the Admin Panel.

Rooms

A room is a collaboration context — usually mapped to a page or view in your app.

<!-- Users on this page collaborate together -->
<pulse-widget room="project-settings" ...></pulse-widget>

<!-- Users on this page are in a different room -->
<pulse-widget room="project-dashboard" ...></pulse-widget>

Users in the same room can:

• See each other's cursors
• See who else is online
• Comment on and discuss the page
• View the activity feed

Users in different rooms are completely separate.

Room Naming

Rooms are created automatically the first time someone joins. Use any string:

Pattern	Example	Use Case
Page path	"/settings"	One room per page
Resource ID	"project-42"	One room per resource
Composite	"project-42/settings"	Resource + section

Threads & Comments

A thread is a conversation. It can be:

• Pinned to a position on the page (click-to-comment)
• Unpinned (created from the comments panel)

Each thread has:

• One or more comments (the first comment is created with the thread)
• A resolved/unresolved status
• An optional position (x/y coordinates on the page)

Comments support:

• @mentions — notify another user by referencing their ID
• Editing — the author can edit their own comment
• Deleting — the author can delete their own comment
• Reactions — emoji reactions from any user

Users

Users are created automatically the first time they connect. The userId and name come from the token you mint on your backend:

{
  "userId": "user-123",
  "name": "Alice Chen",
  "avatar": "https://..."
}

Pulse auto-assigns each user a color from its palette. This color is used for cursors, avatars, and highlights.

Presence

Presence tracks who is currently viewing a page:

• Online — user is active on the page
• Idle — user hasn't interacted for a while
• Offline — user has left the page

The widget shows presence as colored avatar circles in the toolbar.

Notifications

When something relevant happens (someone replies to your comment, @mentions you, or reacts to your comment), Pulse creates a notification. These are scoped to each user and track read/unread state.

What Happens When a User Disconnects?

• Their cursor disappears from other users' screens
• Their presence avatar is removed
• Their comments, threads, and reactions remain (persistent data)
• When they reconnect, they see all the latest data