@clivly/chat-widget 0.7.1 → 0.7.2

package/README.md

@@ -1,155 +1,128 @@
-# `@clivly/chat-widget`
+# @clivly/chat-widget
 
-Embeddable chat widget package for Clivly conversations.
+Embeddable chat widget for Clivly conversations.
 
-> **Preview-quality surface.** Install with `npm install @clivly/chat-widget`.
-> The end-to-end path (SDK session handler, `/widget.js` serving, operator
-> inbox) is implemented and covered by integration tests; treat it as
-> design-partner quality while the conversations UX settles.
+## Install
 
-> **New here?** Start with
-> [Adding the chat widget](../../docs/guides/adding-the-chat-widget.md) — the
-> end-to-end integration guide (widget record, session route, embed, operator
-> inbox). This README is the API-level reference for the package's entrypoints.
+```bash
+npm install @clivly/chat-widget
+```
+
+Peer dependencies:
+
+```bash
+npm install react react-dom
+```
+
+This package is a Tier 2 surface in
+[STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md).
+Stable releases publish on npm's `latest` tag. Use `@next` only when you are
+testing a prerelease build.
 
-This package currently exposes four stable entrypoints with different intended
-use cases.
+For the end-to-end integration flow, start with:
+[Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md).
 
 ## Entrypoints
 
 ### `@clivly/chat-widget`
 
-Use the package root for app-side integration code.
+Use the package root for React components plus browser-safe helpers.
 
-It exports:
+Exports include:
 
-- React widget components
+- `ChatWidget`
+- `ChatLauncher`
+- `ChatPanel`
+- `ConversationView`
+- `MessageComposer`
+- `PreChatForm`
 - `createSessionFetcher()`
 - `createClivlyTransport()`
-- side-effect-free mount helpers
+- `createWebSocketTransport()`
+- `createLoopbackTransport()`
+- `mountChatWidget()`
+- `mountChatWidgetScript()`
+- `autoMountChatWidgetScript()`
 
 Example:
 
 ```ts
 import {
-	createSessionFetcher,
-	createClivlyTransport,
-	mountChatWidget,
+  ChatWidget,
+  createSessionFetcher,
 } from "@clivly/chat-widget";
-
-const getSession = createSessionFetcher({
-	sessionUrl: "/api/clivly/chat/session",
-});
 ```
 
 ### `@clivly/chat-widget/browser`
 
-Use this entry for the browser auto-mount module build.
-
-This entry:
-
-- exports `mountChatWidget()`
-- exports `mountChatWidgetScript()`
-- exports `autoMountChatWidgetScript()`
-- auto-mounts at module evaluation time when `document` exists
-
-This is the module-side equivalent of the script-tag embed behavior.
+Browser entry that auto-mounts at module evaluation time when `document`
+exists. It also exports `mountChatWidget()`, `mountChatWidgetScript()`, and
+`autoMountChatWidgetScript()`.
 
 ### `@clivly/chat-widget/mount`
 
-Use this entry when you want the mount helpers without the browser entry's
+Use this when you want the mounting helpers without the browser entry's
 auto-mount side effect.
 
-This is the safest browser/helper entry for host-controlled mounting.
+### `@clivly/chat-widget/script`
 
-It exports:
+Maps to the generated global bundle at `dist/widget.global.js` for script-tag or
+CDN-style delivery.
 
-- `mountChatWidget()`
-- `mountChatWidgetScript()`
-- `autoMountChatWidgetScript()`
-- `MountChatWidgetOptions`
-- `ChatWidgetMount`
-- `ScriptMountResult`
+## React usage
 
-### `@clivly/chat-widget/script`
+```tsx
+import { ChatWidget, createSessionFetcher } from "@clivly/chat-widget";
+
+<ChatWidget
+  widgetId="support"
+  getSession={createSessionFetcher({
+    sessionUrl: "/api/clivly/widget/session",
+  })}
+/>;
+```
 
-This entry maps to the generated global/browser artifact:
+## Script-tag usage
 
-- `dist/widget.global.js`
+```html
+<script
+  src="https://api.clivly.com/widget.js"
+  data-widget-id="support"
+  data-session-url="/api/clivly/widget/session"
+  defer
+></script>
+```
 
-Use it for script-tag delivery, CDN-style consumption, or any future server path
-that serves the bundled widget directly.
+Supported attributes:
+
+| Attribute | Required | Purpose |
+| --- | --- | --- |
+| `data-widget-id` | yes | Public widget slug from the Clivly dashboard |
+| `data-session-url` | yes | Your backend route that mounts `createChatSessionHandler()` |
+| `data-theme` | no | `auto`, `light`, or `dark` |
+| `data-socket-url-template` | no | Legacy socket override; usually unnecessary |
 
 ## Theming
 
-The widget ships light and dark palettes and follows the host app by default.
-For integration recipes (Tailwind, next-themes, a custom toggle) see
-[the guide's theming section](../../docs/guides/adding-the-chat-widget.md#theming).
+The widget ships light and dark palettes and follows the host by default.
 
-### `theme`
+`theme` accepts:
 
 | Value | Behaviour |
 | --- | --- |
-| `"auto"` *(default)* | Follows the host: `data-theme="dark"`/`"light"` on `<html>`, then a `dark`/`light` class on `<html>`, then `prefers-color-scheme`. Re-resolves live. |
-| `"light"` / `"dark"` | Pinned. Host signals are ignored and nothing is observed. |
+| `"auto"` | Follows `data-theme` on `<html>`, then `dark` / `light` classes on `<html>`, then `prefers-color-scheme` |
+| `"light"` / `"dark"` | Pinned theme |
 
-Set it as a prop (`<ChatWidget theme="dark" />`), as `data-theme` on the script
-tag, or as `theme` in `mountChatWidget()` options. An unrecognised
-`data-theme` value falls back to `"auto"` rather than throwing.
+Set it as a React prop, a script-tag `data-theme`, or through
+`mountChatWidget()` options. `mountChatWidgetScript()` also returns
+`setTheme(theme)` for hosts with a custom toggle.
 
-`mountChatWidgetScript()` also returns `setTheme(theme)` for hosts whose toggle
-does not touch `<html>`:
+The resolved theme is written to `data-clivly-theme="light|dark"` on the widget
+root.
 
-```ts
-const { setTheme } = mountChatWidgetScript(script);
-setTheme("dark");   // pin
-setTheme("auto");   // hand control back to the host
-```
-
-The resolved theme is applied as `data-clivly-theme="light|dark"` on the widget
-root, together with `color-scheme`, so native scrollbars, autofill, and the
-caret follow the panel.
-
-### Palette tokens
-
-Every colour reads through a CSS custom property. React hosts can override any
-of them inline — inline declarations beat both palette rules, so no specificity
-work is needed:
-
-```tsx
-<ChatWidget style={{ "--clivly-chat-panel": "#0b0f19" }} widgetId="support" />
-```
-
-| Token | Light | Dark |
-| --- | --- | --- |
-| `--clivly-chat-accent` | `#185adb` | `#4f8cff` |
-| `--clivly-chat-accent-contrast` | `#ffffff` | `#0b1220` |
-| `--clivly-chat-panel` | `#ffffff` | `#111827` |
-| `--clivly-chat-input` | `transparent` | `#0b1220` |
-| `--clivly-chat-border` | `#d6dde8` | `#2a3546` |
-| `--clivly-chat-text` | `#132238` | `#e8edf5` |
-| `--clivly-chat-muted` | `#60738a` | `#93a2b8` |
-| `--clivly-chat-visitor` | `#ecf3ff` | `#1e3a6b` |
-| `--clivly-chat-operator` | `#f5f7fa` | `#1b2534` |
-| `--clivly-chat-shadow` | `rgba(19, 34, 56, 0.18)` | `rgba(0, 0, 0, 0.5)` |
-| `--clivly-chat-error-bg` | `#fff1f1` | `#2c1618` |
-| `--clivly-chat-error-border` | `#f2c2c2` | `#5c2a2e` |
-| `--clivly-chat-error-text` | `#9f2d2d` | `#ffb4b4` |
-
-The widget record's `brandColor` overrides `--clivly-chat-accent` in **both**
-themes — the widget will not silently lighten your brand. If your brand colour
-is very dark it will be low-contrast on the dark panel; pick a lighter accent,
-or override the token per theme in a React host.
-
-Deep per-token overrides are not available on the script-tag path: it mounts
-into a Shadow DOM, so host CSS cannot reach the widget's internals. Use
-`brandColor` and the two themes there.
-
-## Session bootstrap shape
-
-The widget expects a session bootstrap endpoint that returns a
-`WidgetSessionPayload`.
+## Session bootstrap
 
+The widget expects a bootstrap endpoint that returns a `WidgetSessionPayload`.
 Important fields include:
 
 - `token`
@@ -159,39 +132,21 @@ Important fields include:
 - `messages`
 - optional `socketUrl`
 
-When `socketUrl` is present, the widget prefers it over reconstructing the
-socket URL from a client-side template.
-
-## Transport behavior
+When `socketUrl` is present, the widget prefers it over reconstructing one from
+`socketUrlTemplate`.
 
-The package includes:
+## Transport behaviour
 
-- `createClivlyTransport()` for real Clivly backends
-- `createWebSocketTransport()` for explicit socket wiring
-- `createLoopbackTransport()` for local UI/testing flows
+The default browser mount order is:
 
-The default browser mount behavior is:
-
-1. use a caller-provided `createTransport` when present
+1. use a caller-provided `createTransport`
 2. otherwise prefer `session.socketUrl`
-3. otherwise fall back to `socketUrlTemplate` when provided
-
-## Build outputs
-
-The package currently produces:
+3. otherwise fall back to `socketUrlTemplate`
 
-- `dist/index.*`
-- `dist/browser.*`
-- `dist/browser-mount.*`
-- `dist/widget.global.js`
+## Host-side session route
 
-The `browser` and `browser-mount` outputs are built as standalone entrypoints.
-
-## Host-side pairing
-
-The host-side session handler is the bridge between a backend holding
-`CLIVLY_SECRET_KEY` and the widget's `sessionUrl`. Import it from `clivly/sdk`,
-which is available from the `clivly` package `clivly init` already installs:
+The widget talks to your backend, not directly to Clivly. Mount the session
+handler from the SDK on your own origin:
 
 ```ts
 import { createChatSessionHandler } from "clivly/sdk";
@@ -201,10 +156,23 @@ export const POST = createChatSessionHandler({
 });
 ```
 
-`@clivly/sdk` exports the same handler if you depend on it directly. Don't import
-from `clivly` (the package root) — that entry is the CLI and is Node-only.
+The current scaffolded/default route path is:
+
+```text
+/api/clivly/widget/session
+```
+
+Use the handler rather than hand-writing the proxy. It forwards `origin`
+correctly, accepts `visitorToken: null` for first-time visitors, and returns a
+clean JSON `502` when Clivly is unreachable.
+
+## More docs
+
+- End-to-end guide:
+  [Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+- Release notes:
+  [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
+
+## License
 
-Use the handler rather than hand-writing the proxy: it puts `origin` in the
-request body (the backend requires it there, and only falls back to the `Origin`
-header), accepts `visitorToken: null` for a first-time visitor, and turns an
-unreachable Clivly into a JSON `502` instead of a thrown `fetch`.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/chat-widget",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "private": false,
   "type": "module",
   "description": "Clivly chat widget — embeddable React and script-tag entrypoints for Clivly conversations.",