Skip to content

docs(guide): point the embeddable-widget path at @smooai/chat-widget (Aurora Glass) #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brentrager merged 1 commit into from
Jun 25, 2026
Merged

docs(guide): point the embeddable-widget path at @smooai/chat-widget (Aurora Glass) #116

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 39 additions & 15 deletions docs/Guides/React Components and Custom UIs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,17 @@

smooth-operator's frontend story is **layered and modular** — you can adopt as
much or as little UI as you want, because every layer sits on the same
schema-driven WebSocket protocol. And it's all **one package**,
`@smooai/smooth-operator`, with subpath exports — install once, import the layer
you need:
schema-driven WebSocket protocol. The headless client + React layers ship in
**one package**, `@smooai/smooth-operator` (subpath exports — install once,
import the layer you need); the no-build embeddable chat widget is the separate,
**canonical** public package **`@smooai/chat-widget`** (the "Aurora Glass"
design), which consumes the same client under the hood:

```mermaid
flowchart TD
P["WebSocket protocol<br/>(spec/ — language-neutral)"]
C["@smooai/smooth-operator<br/>headless TS client"]
W["@smooai/smooth-operator/widget<br/>web component (any framework / no build)"]
W["@smooai/chat-widget (Aurora Glass)<br/>web component (any framework / no build)"]
H["@smooai/smooth-operator/react · useConversation<br/>headless hook (your own UI)"]
S["@smooai/smooth-operator/react · &lt;SmoothChat&gt;<br/>styled component (CSS-variable themed)"]
P --> C --> W
Expand All @@ -19,20 +21,22 @@ flowchart TD

| You want… | Import |
| ------------------------------------------------------ | -------------------------------------------- |
| Chat on a page, any framework, maybe no build step | `@smooai/smooth-operator/widget` (web component) |
| Chat on a page, any framework, maybe no build step | `@smooai/chat-widget` (Aurora Glass web component) |
| A React app, your own components, full design control | `@smooai/smooth-operator/react` → `useConversation` |
| A React app, batteries-included chat to theme | `@smooai/smooth-operator/react` → `<SmoothChat>` |
| Another language, or a totally custom surface | the [[Using the Polyglot Clients\|clients]] directly |

One install gives you all of it:
One install gives you the client + React layers:

```bash
pnpm add @smooai/smooth-operator react react-dom
# embeddable widget (no React needed): pnpm add @smooai/chat-widget
```

`react` / `react-dom` are **optional** peer deps — only needed if you import the
`./react` subpath. A client-only or widget-only consumer never pulls React into
their bundle (subpath exports + `sideEffects` keep it tree-shaken out).
`./react` subpath. A client-only consumer never pulls React into their bundle
(subpath exports + `sideEffects` keep it tree-shaken out), and the embeddable
`@smooai/chat-widget` is framework-agnostic (no React on the host page at all).

## Headless first — `useConversation`

Expand Down Expand Up @@ -64,25 +68,45 @@ import '@smooai/smooth-operator/react/styles.css'; // once, anywhere
<SmoothChat url="wss://your-host/ws" agentId={agentId} agentName="Support" greeting="How can I help?" />;
```

## No-React option — the web-component widget
## No-React option — the embeddable widget (`@smooai/chat-widget`)

If you're not on React (or want a no-build `<script>` embed), the same UI ships
as a framework-agnostic custom element on the `./widget` subpath:
If you're not on React (or want a no-build `<script>` embed), use the canonical
public widget **`@smooai/chat-widget`** (the "Aurora Glass" design) — a
self-contained `<smooth-agent-chat>` custom element that speaks the same protocol
(it consumes `@smooai/smooth-operator`'s client internally). This is the single
widget that smooth-operator's own [[Deploy Architecture|local-flavor server]]
serves, the marketing demos embed, and you should reach for:

```ts
import { mountChatWidget } from '@smooai/smooth-operator/widget';
import { mountChatWidget } from '@smooai/chat-widget';
mountChatWidget({ endpoint: 'wss://your-host/ws', agentId });
```

Or drop the standalone IIFE on any page — no bundler, no framework:
For a no-bundler `<script>` embed, the **deferred loader** is recommended (best
Core Web Vitals — it does nothing expensive on the host page until the user shows
intent, then injects the full widget):

```html
<script src="https://unpkg.com/@smooai/smooth-operator/dist/widget/chat-widget.iife.js"></script>
<script>
window.SmoothAgentChatConfig = { endpoint: 'wss://your-host/ws', agentId: '…' };
</script>
<script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget-loader.global.js" async></script>
```

Or drop the eager standalone IIFE directly:

```html
<script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget.global.js"></script>
<smooth-agent-chat endpoint="wss://your-host/ws" agent-id="…"></smooth-agent-chat>
```

The widget is themed with the same palette keys (`ChatWidgetTheme`) as the React
components, so a brand ports between them unchanged.
components, so a brand ports between them unchanged. Full embed docs live in the
[`@smooai/chat-widget` README](https://github.com/SmooAI/chat-widget#readme).

> The `@smooai/smooth-operator` SDK also still ships a `./widget` export (an
> older in-tree copy of this component); prefer `@smooai/chat-widget` — it's the
> canonical, separately-versioned public widget.

## Theming with CSS variables (not a build coupling)

Expand Down