npm package: @peacethinking/widget
Description: Embeddable Web Component for escalation detection and graduated intervention
Latest version: 0.1.0

# @peacethinking/widget

[![npm](https://img.shields.io/npm/v/@peacethinking/widget)](https://www.npmjs.com/package/@peacethinking/widget)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

Embeddable Web Component for real-time escalation detection and graduated intervention. Drop a single `<script>` tag into any website — forums, comment sections, chat applications — and get Gottman-based conflict detection with automatic nudges, reflection prompts, and mediation offers. Shadow DOM for complete style isolation.

## Quick Start

```html
<script src="https://cdn.peacethinking.ai/widget.js"></script>
<peacethinking-widget
  api-key="pk_live_..."
  thread-selector=".forum-post"
  lang="en"
  theme="auto"
></peacethinking-widget>
```

Or self-host the bundle:

```bash
npm install @peacethinking/widget
# Copy dist/widget.js to your static assets
```

## How It Works

1. The widget observes DOM elements matching `thread-selector`
2. Each message is scored for escalation (rule-based, zero latency)
3. When the score crosses `min-score`, a graduated intervention appears:

| Stage | Score | Intervention |
|-------|-------|-------------|
| Nudge | 0.4+ | Gentle communication tip, visible only to the author |
| Reflection | 0.6+ | Pause prompt — "What is your actual concern?" |
| Cooldown | 0.75+ | Rate-limiting suggestion for the thread |
| Mediation | 0.85+ | Offer to resolve on Peacethinking platform |

## Attributes

| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `api-key` | string | — | API key for server-side detection (`pk_live_*`) |
| `thread-selector` | string | `.thread` | CSS selector for message elements to observe |
| `lang` | `en` \| `de` | `en` | UI language |
| `theme` | `auto` \| `light` \| `dark` | `auto` | Color scheme |
| `mode` | `local` \| `api` \| `hybrid` \| `challenge` | `local` | Detection mode |
| `min-score` | number | `0.4` | Minimum escalation score to trigger intervention |
| `demo-mode` | `true` \| `false` | `false` | Enable demo mode with sample data |
| `enable-dialog-starter` | `true` \| `false` | `false` | Show dialogue creation panel |
| `enable-interest-pool` | `true` \| `false` | `false` | Show interest pool for topic voting |
| `enable-embedded` | `true` \| `false` | `false` | Enable embedded dialogue view |
| `enable-insights` | `true` \| `false` | `false` | Show community health insights |

## Detection Modes

| Mode | Description |
|------|-------------|
| `local` | Rule-based detection only (OSS, zero latency, no API calls) |
| `api` | Server-side detection via Peacethinking API (requires `api-key`) |
| `hybrid` | Local first, API for confirmation above threshold |
| `challenge` | Public dialogue challenge mode |

## Sub-Panels

The widget includes optional panels activated via attributes:

- **Dialog Starter**: Create structured dialogues from escalated threads
- **Interest Pool**: Community topic voting for proactive conflict prevention
- **Embedded Dialogue**: Full mediation view within the widget
- **Challenge Card**: Public dialogue challenge integration
- **Insights**: Community health analytics dashboard

## Part of the Peacethinking Ecosystem

`@peacethinking/widget` is the embeddable frontend of the Peacethinking Resolution Platform.

| Package | Description |
|---------|-------------|
| [`@peacethinking/conflict-framework`](https://www.npmjs.com/package/@peacethinking/conflict-framework) | Shared types, schemas, and the 6-Dimensions Conflict Framework |
| [`@peacethinking/escalation-detector`](https://www.npmjs.com/package/@peacethinking/escalation-detector) | Hybrid escalation detection — rule-based (OSS) + LLM-enhanced |
| [`@peacethinking/mediation-prompts`](https://www.npmjs.com/package/@peacethinking/mediation-prompts) | LLM prompt builders for verdict, perspective, and mediation flows |
| [`@peacethinking/mediation-workflows`](https://www.npmjs.com/package/@peacethinking/mediation-workflows) | XState-based mediation state machines and templates |
| [`@peacethinking/llm-eval`](https://www.npmjs.com/package/@peacethinking/llm-eval) | Benchmark any LLM on conflict resolution scenarios |
| [`@peacethinking/mcp-server`](https://www.npmjs.com/package/@peacethinking/mcp-server) | MCP server for AI agent integration |

## License

MIT — see [LICENSE](./LICENSE).

Built by [peacethinking.ai](https://peacethinking.ai).