Widget

The <pleiades-chat> widget

A single framework-agnostic web component. It shows a launcher button in a corner of the page and opens a side panel with the chat. It lives in a shadow root, so the host page's CSS cannot break it. It works the same in plain HTML, React, Vue, Svelte or Angular.

Install

From npm:

npm install @shalotts/pleiades-widget

import "@shalotts/pleiades-widget"; // registers <pleiades-chat>; there are no exports

Or with a script tag (jsDelivr or unpkg serve the same file):

<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>

agent-url and publishable-key come from your channel in the admin panel. The widget also installs a WebMCP polyfill on pages without native support, so your tools work in any browser.

If the configuration is wrong the element renders nothing and logs one [pleiades-widget] <code> line to the console. See Errors .

Attributes

All configuration is through attributes. Changing one re-mounts the widget.

Dictation uses the browser's Web Speech API where it exists. The microphone button is dimmed where it does not.

Element methods and properties

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

send()

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

resetSession()

The orchestrator keeps per-conversation facts (which store is open, the last product found). A page that swaps one app for another should reset on every switch:

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

Different sites should use separate channels (one publishable-key each); switching the key gives each its own conversation, kept across reloads.

Theming

Set CSS variables on the element:

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

For anything beyond tokens, use CSS Shadow Parts:

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

Parts present in the templates: launcher, panel, header, close, messages, error, mode, hint, tooltip, composer, input, send, mic, link.

@shalotts/pleiades-widget/style.css is the exact stylesheet the widget injects into its shadow root. Use it as a reference for class names; linking it into a page does nothing, because shadow DOM does not apply it there.

Types

The package ships TypeScript declarations, including the HTMLElementTagNameMap entry, so document.querySelector("pleiades-chat") is typed. For React JSX, import the augmentation once:

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

Errors

Configuration errors are logged once as [pleiades-widget] <code>: <advice> and nothing is rendered.

A bad customer-context logs invalid_customer_context and is dropped; the widget still works.

Runtime failures show in the panel. They map from the API status : no answer is a network error and locks the composer, 403 is forbidden, 413 is "too long", 429 is rate limited, a terminal stream error with code: "task_failed" shows the site's advice and never locks the composer. An origin the channel does not allow looks like a network error in the browser: the server answers 403 without CORS headers, so the browser hides the reason.

Security

• Only pk_ keys. The widget refuses to start with an sk_ key. A secret key belongs on your server, for identify .
• https only for agent-url, except localhost, so the visitor token never travels in clear text.
• Allowed origins. The channel lists the origins that may use it; the server checks the Origin header, which a browser cannot fake. A copied key is useless on another site.
• No secret in the page. The key is sent once, to get a visitor token. Every later request carries only the token.
• Requests use credentials: "omit" and cache: "no-store": no cookies, nothing cached.
• The token and thread id are kept in localStorage under a name derived from agent URL and key, so two sites never share a session. If storage is blocked the widget falls back to memory.
• Message text is rendered with textContent, never as HTML.
• Do not put sensitive data in customer-context. Keep it to a few short facts (country, city, a tier label), never names, emails or phone numbers.
• Tools registered on a page are untrusted data for the orchestrator, and without expose-tools-to no other window can reach them.

If you host the script yourself, pin it with Subresource Integrity.