npm package: @gamention/pulse-elements
Description: Drop-in web components for real-time collaboration — comments, cursors, presence, drawing, and more
Author: Krishna Thorat
Latest version: 0.3.7

# @gamention/pulse-elements

Drop-in web components for real-time collaboration — **comments, cursors, presence, drawing, notifications, and more**. Built with [Lit](https://lit.dev/), works with any framework.

## Installation

```bash
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:

```html
<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)

```html
<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:**
```tsx
import '@gamention/pulse-elements';

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

**Vue:**
```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

```html
<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:

```css
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:

```bash
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](https://pulse.hire.rest/docs)**

- [Quick Start](https://pulse.hire.rest/docs/getting-started/quickstart)
- [Widget Setup](https://pulse.hire.rest/docs/widget/setup)
- [Theming](https://pulse.hire.rest/docs/widget/theming)
- [Framework Guides](https://pulse.hire.rest/docs/widget/frameworks) (React, Vue, Svelte, Angular, Next.js)
- [REST API](https://pulse.hire.rest/docs/api/overview)

## Related Packages

- [`@gamention/pulse-core`](https://www.npmjs.com/package/@gamention/pulse-core) — Core client SDK for building custom UI
- [`@gamention/pulse-shared`](https://www.npmjs.com/package/@gamention/pulse-shared) — Shared TypeScript types and protocol

## License

MIT