# Виджет `<pleiades-chat>`

Один веб-компонент, не привязанный к фреймворку. Он показывает кнопку-лаунчер в углу страницы и открывает боковую панель с чатом. Компонент живёт в shadow root, поэтому CSS страницы-хозяина не может его сломать. Он одинаково работает в обычном HTML, React, Vue, Svelte и Angular.

## Установка

<Tabs activeName="unpkg">
<TabPanel name="unpkg">

```html
<script src="https://unpkg.com/@shalotts/pleiades-widget/dist/pleiades-widget.js" defer></script>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="jsDelivr">

```html
<script src="https://cdn.jsdelivr.net/npm/@shalotts/pleiades-widget/dist/pleiades-widget.js" defer></script>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="npm">

```sh
npm install @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="pnpm">

```sh
pnpm add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="bun">

```sh
bun add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="npm:jsr">

```sh
npx jsr add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="pnpm:jsr">

```sh
pnpm dlx jsr add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
<TabPanel name="bun:jsr">

```sh
bunx jsr add @shalotts/pleiades-widget
```

```js
import "@shalotts/pleiades-widget"; // registers <pleiades-chat>

<pleiades-chat
  agent-url="https://agent.example.com"
  publishable-key="pk_your_channel_key"
></pleiades-chat>
```

</TabPanel>
</Tabs>

Нужен только [полифил WebMCP](/ru/docs/polyfill/), без чата? Это отдельная точка входа того же пакета (виджет ставит его сам):

```js
import { installWebMcpPolyfill } from "@shalotts/pleiades-widget/webmcp-polyfill";

installWebMcpPolyfill();
```

`agent-url` и `publishable-key` берутся из вашего канала в админ-панели. На страницах без нативной поддержки виджет также устанавливает [полифил WebMCP](/ru/docs/polyfill/), поэтому ваши [инструменты](/ru/docs/tools/) работают в любом браузере.

Если конфигурация неверна, элемент ничего не рисует и пишет в консоль одну строку `[pleiades-widget] <code>`. См. [Ошибки](#Ошибки).

## Атрибуты

Вся настройка выполняется через атрибуты. Изменение любого из них перемонтирует виджет.

| Атрибут | По умолчанию | Описание |
| --- | --- | --- |
| `agent-url` | обязателен | Базовый URL оркестратора. Только `https`; обычный `http` допускается для `localhost`, `127.0.0.1` и `[::1]`. Без имени пользователя и пароля в URL. |
| `publishable-key` | обязателен | Публичный ключ канала. Должен соответствовать `pk_` и не менее 8 символов из `A-Za-z0-9_-` после него. |
| `position` | `bottom-left` | Угол лаунчера: `bottom-left`, `bottom-right`, `top-left`, `top-right`. Панель выезжает с той же стороны. Неизвестные значения заменяются на `bottom-left`. |
| `heading` | локализуется | Заголовок панели. |
| `greeting` | локализуется | Первое сообщение-пузырь. |
| `placeholder` | локализуется | Подсказка в поле сообщения. |
| `lang` | `<html lang>`, иначе язык браузера | `en`, `ru` или `kk`. Учитываются только первые две буквы (`ru-RU` работает); всё остальное — английский. |
| `customer-context` | нет | Плоский JSON-объект с фактами, которые сайт уже знает, например `'{"city":"Almaty","tier":"gold"}'`. Значения должны быть строками, числами или булевыми; остальные поля отбрасываются с ошибкой в консоли. Отправляется с каждым сообщением. |
| `hotkey` | `mod+j` | Открывает и закрывает панель. `mod` — это Ctrl, а на Mac — Cmd. Другие примеры: `ctrl+shift+k`, `alt+/`. Пустое значение отключает. |
| `mic-hotkey` | `mod+shift+space` | Запускает и останавливает диктовку, пока панель открыта. Тот же формат. Пустое значение отключает. |
| `expose-tools-to` | нет | Origin'ы через запятую (`https://a.example,https://b.example`), окна которых могут получать список и запускать инструменты этой страницы через `postMessage`. `*` и некорректные origin'ы игнорируются. См. [Инструменты](/ru/docs/tools/#Инструменты-в-других-окнах). |
| `examples` | встроенные три | До трёх подсказок, которые показываются до первого сообщения: JSON-массив строк, `'["Find a jacket","Where is my order?"]'`. `'[]'` скрывает их. Если значение не разбирается, остаются встроенные. |
| `open` | отсутствует | Булев атрибут. Панель стартует открытой. Также есть свойство `open`. |
| `test-api` | отсутствует | Булев атрибут. Дополнительно открывает `window.pleiadesChat.send(text)` для автоматизации браузера. По умолчанию выключен: на боевых страницах глобальной переменной нет. |

Диктовка использует Web Speech API браузера там, где он есть. Там, где его нет, кнопка микрофона затемнена.

## Методы и свойства элемента

```js
const chat = document.querySelector("pleiades-chat");
```

| Член | Описание |
| --- | --- |
| `chat.open` | Свойство, отражающее атрибут `open`. Установите его, чтобы открыть или закрыть панель. |
| `chat.toggle()` | Переключает `open`. |
| `chat.send(text)` | Отправляет `text`, как будто посетитель набрал его и нажал «Отправить». Открывает панель, выполняет вызовы инструментов страницы и завершается (resolve), когда ход заканчивается. Никогда не отклоняется (reject). |
| `chat.resetSession()` | Новый разговор для того же посетителя: новый тред, пустая панель, инструменты страницы объявляются заново. Никогда не отклоняется. |
| `chat.getVisitorToken()` | Возвращает токен посетителя этого браузера (при необходимости создавая сессию) или `undefined`, пока элемент не настроен. Передайте его на свой сервер для [`identify`](/ru/docs/api/server/#Идентификация-посетителя). |
| `chat.agentUrl`, `publishableKey`, `position`, `heading`, `greeting`, `placeholder`, `lang`, `customerContext`, `examples`, `hotkey`, `micHotkey`, `exposeToolsTo` | Свойства, зеркалирующие атрибуты (строки). Присвоение `null` или `undefined` удаляет атрибут. |

### `send()`

```js
const r = await chat.send("book a double room for two nights from Friday");
// { requestId?, reply, steps: [{ text, phase }], status: "done" | "failed" | "error", error? }
```

| Поле | Значение |
| --- | --- |
| `status: "done"` | Цель достигнута. |
| `status: "failed"` | Сервер отработал, но сайт не смог выполнить задачу. В `error` лежит последний ответ самого сайта, если он есть. |
| `status: "error"` | Занято, не настроено, сообщение слишком длинное, сбой сервера или остановка. `error` говорит, что именно произошло. |
| `reply` | Итоговый текст ассистента за этот ход. |
| `steps` | Строки прогресса, показанные за ход; `phase` — `running`, `done` или `failed`. |
| `requestId` | Id первого `tool_call` хода (открывает запуск в админ-панели `/flow/<id>`). Отсутствует, если в ходе не было вызова инструмента на стороне браузера. |

### `resetSession()`

Оркестратор хранит факты по каждому разговору (какой магазин открыт, последний найденный товар). Страница, которая подменяет одно приложение другим, должна сбрасывать сессию при каждом переключении:

```js
picker.addEventListener("change", () => chat.resetSession());
```

Разным сайтам следует использовать отдельные каналы (по одному `publishable-key` на каждый); при смене ключа у каждого свой разговор, который сохраняется между перезагрузками.

## Темизация

Задайте CSS-переменные на элементе:

| Переменная | Назначение |
| --- | --- |
| `--pleiades-accent`, `--pleiades-accent-fg` | Акцентный цвет и цвет текста на нём. |
| `--pleiades-bg`, `--pleiades-fg` | Фон панели и текст. |
| `--pleiades-muted`, `--pleiades-muted-fg` | Второстепенные поверхности и текст. |
| `--pleiades-border` | Границы. |
| `--pleiades-destructive`, `--pleiades-destructive-fg` | Цвет ошибки и цвет текста на нём. |
| `--pleiades-font-family` | Шрифт. |
| `--pleiades-font-scale` | Множитель всех размеров текста; по умолчанию `1.5`. Значение `1` даёт компактную базу 14 px. |

```css
pleiades-chat {
  --pleiades-accent: #0b6e4f;
  --pleiades-accent-fg: #fff;
  --pleiades-font-family: "Inter", sans-serif;
}
```

Для всего, что выходит за рамки токенов, используйте CSS Shadow Parts:

```css
pleiades-chat::part(panel) { border-radius: 0; }
pleiades-chat::part(send)  { text-transform: uppercase; }
```

Части (parts) в шаблонах: `launcher`, `panel`, `header`, `close`, `messages`, `error`, `mode`, `hint`, `tooltip`, `composer`, `input`, `send`, `mic`, `link`.

`@shalotts/pleiades-widget/style.css` — это точная таблица стилей, которую виджет внедряет в свой shadow root. Используйте её как справочник по именам классов; подключение её к странице ничего не даёт, потому что shadow DOM не применяет её там.

## Типы

Пакет поставляется с объявлениями TypeScript, включая запись `HTMLElementTagNameMap`, поэтому `document.querySelector("pleiades-chat")` типизирован. Для React JSX один раз импортируйте расширение типов:

```ts
import type {} from "@shalotts/pleiades-widget/react";
```

## Ошибки

Ошибки конфигурации один раз пишутся в консоль как `[pleiades-widget] <code>: <advice>`, и ничего не рисуется.

| Код | Причина |
| --- | --- |
| `missing_agent_url` | `agent-url` пуст. |
| `invalid_agent_url` | Это не http(s) URL либо в нём есть имя пользователя или пароль. |
| `insecure_agent_url` | `http` к хосту, отличному от localhost. |
| `missing_key` | `publishable-key` пуст. |
| `secret_key` | Ключ начинается с `sk_`. Считайте его скомпрометированным и замените. |
| `invalid_key` | Это не ключ `pk_` ожидаемого вида. |

Некорректный `customer-context` пишет `invalid_customer_context` и отбрасывается; виджет продолжает работать.

Ошибки времени выполнения отображаются в панели. Они сопоставляются со [статусами API](/ru/docs/api/widget/#Статусы-ошибок): отсутствие ответа — сетевая ошибка, и поле ввода блокируется; `403` — запрещено; `413` — «слишком длинно»; `429` — превышен лимит запросов; завершающая `error` потока с `code: "task_failed"` показывает совет сайта и никогда не блокирует поле ввода. Origin, который канал не разрешает, выглядит в браузере как сетевая ошибка: сервер отвечает `403` без заголовков CORS, поэтому браузер скрывает причину.

## Безопасность

- **Только ключи `pk_`.** Виджет отказывается запускаться с ключом `sk_`. Секретный ключ должен храниться на вашем сервере, для [`identify`](/ru/docs/api/server/#Идентификация-посетителя).
- **Только https** для `agent-url`, кроме localhost, чтобы токен посетителя никогда не передавался открытым текстом.
- **Разрешённые origin'ы.** Канал перечисляет origin'ы, которым разрешено его использовать; сервер проверяет заголовок `Origin`, который браузер подделать не может. Скопированный ключ на другом сайте бесполезен.
- **Никаких секретов на странице.** Ключ отправляется один раз, чтобы получить токен посетителя. Все последующие запросы несут только токен.
- Запросы используют `credentials: "omit"` и `cache: "no-store"`: без cookie и без кеширования.
- Токен и id треда хранятся в `localStorage` под именем, производным от URL агента и ключа, поэтому два сайта никогда не делят сессию. Если хранилище заблокировано, виджет переключается на память.
- Текст сообщений отображается через `textContent`, а не как HTML.
- Не помещайте чувствительные данные в `customer-context`. Ограничьтесь несколькими короткими фактами (страна, город, метка тарифа), но не именами, адресами электронной почты или номерами телефонов.
- Инструменты, зарегистрированные на странице, для оркестратора — недоверенные данные, а без `expose-tools-to` никакое другое окно не может до них добраться.

Если вы размещаете скрипт самостоятельно, закрепите его с помощью Subresource Integrity.
