@gamention/pulse-elements

Drop-in web components for real-time collaboration — comments, cursors, presence, drawing, notifications, and more. Built with Lit, works with any framework.

Installation

npm install @gamention/pulse-elements

Quick Start

Option 1: Single Widget (Recommended)

One tag gives you everything — comments, cursors, presence, drawing, notifications, pins, and activity feed:

<pulse-widget
  api-key="pk_..."
  token="YOUR_JWT_TOKEN"
  room="my-page"
  endpoint="wss://pulse.hire.rest"
></pulse-widget>

<script type="module">
  import '@gamention/pulse-elements';
</script>

Option 2: CDN (No Build Step)

<script src="https://pulse.hire.rest/sdk/pulse.js"></script>

<pulse-widget
  api-key="pk_..."
  token="YOUR_JWT_TOKEN"
  room="my-page"
  endpoint="wss://pulse.hire.rest"
></pulse-widget>

Option 3: Framework Integration

React:

import '@gamention/pulse-elements';

function App() {
  return (
    <pulse-widget
      api-key="pk_..."
      token={token}
      room="dashboard"
      endpoint="wss://pulse.hire.rest"
    />
  );
}

Vue:

<template>
  <pulse-widget
    :api-key="apiKey"
    :token="token"
    room="dashboard"
    endpoint="wss://pulse.hire.rest"
  />
</template>

<script setup>
import '@gamention/pulse-elements';
</script>

Features

| Feature | Description | |---------|-------------| | Comments | Threaded comments with @mentions, edit/delete, reactions | | Pin Anywhere | Click anywhere on the page to pin a comment (element-anchored, works across viewports) | | Live Cursors | See other users' cursors in real-time | | Presence | Online/idle status with avatars | | Drawing | Freehand annotations with auto-fade (pen pressure support) | | Notifications | Bell icon with unread badge for replies, mentions, reactions | | Activity Feed | Chronological room activity log | | Media Attachments | Image uploads with lightbox, audio notes (WhatsApp-style), video notes (Telegram-style) | | Follow Mode | Click an avatar to auto-scroll with another user | | Mobile Support | Touch/pen events, responsive bottom-sheet panels, 44px touch targets |

Widget Configuration

<pulse-widget
  api-key="pk_..."        <!-- Publishable API key -->
  token="..."             <!-- JWT from your backend via POST /auth/token -->
  room="page-id"          <!-- Room identifier (one per page/view) -->
  endpoint="wss://..."    <!-- Your Pulse server URL -->
  position="bottom-right" <!-- bottom-right | bottom-left | top-right | top-left -->
  display="floating"      <!-- floating (fixed position) | inline (in page flow) -->
></pulse-widget>

Theming

Override CSS custom properties to match your brand:

pulse-widget {
  --pulse-primary: #e11d48;
  --pulse-bg: #ffffff;
  --pulse-text: #0f172a;
  --pulse-border: #e2e8f0;
  --pulse-radius: 12px;
  --pulse-font: 'Inter', sans-serif;
}

Auth Flow

Your backend mints JWT tokens using a secret key:

curl -X POST https://pulse.hire.rest/auth/token \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "name": "Alice"}'

Pass the returned token to the widget's token attribute.

Documentation

Full docs at pulse.hire.rest/docs

• Quick Start
• Widget Setup
• Theming
• Framework Guides (React, Vue, Svelte, Angular, Next.js)
• REST API

Related Packages

• @gamention/pulse-core — Core client SDK for building custom UI
• @gamention/pulse-shared — Shared TypeScript types and protocol

License

MIT