@clivly/chat-widget 0.7.2 → 0.7.3

package/README.md

@@ -1,128 +1,155 @@
-# @clivly/chat-widget
+# `@clivly/chat-widget`
 
-Embeddable chat widget for Clivly conversations.
+Embeddable chat widget package for Clivly conversations.
 
-## Install
+> **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.
 
-```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.
+> **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.
 
-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).
+This package currently exposes four stable entrypoints with different intended
+use cases.
 
 ## Entrypoints
 
 ### `@clivly/chat-widget`
 
-Use the package root for React components plus browser-safe helpers.
+Use the package root for app-side integration code.
 
-Exports include:
+It exports:
 
-- `ChatWidget`
-- `ChatLauncher`
-- `ChatPanel`
-- `ConversationView`
-- `MessageComposer`
-- `PreChatForm`
+- React widget components
 - `createSessionFetcher()`
 - `createClivlyTransport()`
-- `createWebSocketTransport()`
-- `createLoopbackTransport()`
-- `mountChatWidget()`
-- `mountChatWidgetScript()`
-- `autoMountChatWidgetScript()`
+- side-effect-free mount helpers
 
 Example:
 
 ```ts
 import {
-  ChatWidget,
-  createSessionFetcher,
+	createSessionFetcher,
+	createClivlyTransport,
+	mountChatWidget,
 } from "@clivly/chat-widget";
+
+const getSession = createSessionFetcher({
+	sessionUrl: "/api/clivly/chat/session",
+});
 ```
 
 ### `@clivly/chat-widget/browser`
 
-Browser entry that auto-mounts at module evaluation time when `document`
-exists. It also exports `mountChatWidget()`, `mountChatWidgetScript()`, and
-`autoMountChatWidgetScript()`.
+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.
 
 ### `@clivly/chat-widget/mount`
 
-Use this when you want the mounting helpers without the browser entry's
+Use this entry when you want the mount helpers without the browser entry's
 auto-mount side effect.
 
-### `@clivly/chat-widget/script`
-
-Maps to the generated global bundle at `dist/widget.global.js` for script-tag or
-CDN-style delivery.
+This is the safest browser/helper entry for host-controlled mounting.
 
-## React usage
+It exports:
 
-```tsx
-import { ChatWidget, createSessionFetcher } from "@clivly/chat-widget";
-
-<ChatWidget
-  widgetId="support"
-  getSession={createSessionFetcher({
-    sessionUrl: "/api/clivly/widget/session",
-  })}
-/>;
-```
+- `mountChatWidget()`
+- `mountChatWidgetScript()`
+- `autoMountChatWidgetScript()`
+- `MountChatWidgetOptions`
+- `ChatWidgetMount`
+- `ScriptMountResult`
 
-## Script-tag usage
+### `@clivly/chat-widget/script`
 
-```html
-<script
-  src="https://api.clivly.com/widget.js"
-  data-widget-id="support"
-  data-session-url="/api/clivly/widget/session"
-  defer
-></script>
-```
+This entry maps to the generated global/browser artifact:
 
-Supported attributes:
+- `dist/widget.global.js`
 
-| 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 |
+Use it for script-tag delivery, CDN-style consumption, or any future server path
+that serves the bundled widget directly.
 
 ## Theming
 
-The widget ships light and dark palettes and follows the host by default.
+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).
 
-`theme` accepts:
+### `theme`
 
 | Value | Behaviour |
 | --- | --- |
-| `"auto"` | Follows `data-theme` on `<html>`, then `dark` / `light` classes on `<html>`, then `prefers-color-scheme` |
-| `"light"` / `"dark"` | Pinned theme |
+| `"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. |
 
-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.
+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.
 
-The resolved theme is written to `data-clivly-theme="light|dark"` on the widget
-root.
+`mountChatWidgetScript()` also returns `setTheme(theme)` for hosts whose toggle
+does not touch `<html>`:
 
-## Session bootstrap
+```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`.
 
-The widget expects a bootstrap endpoint that returns a `WidgetSessionPayload`.
 Important fields include:
 
 - `token`
@@ -132,21 +159,39 @@ Important fields include:
 - `messages`
 - optional `socketUrl`
 
-When `socketUrl` is present, the widget prefers it over reconstructing one from
-`socketUrlTemplate`.
+When `socketUrl` is present, the widget prefers it over reconstructing the
+socket URL from a client-side template.
+
+## Transport behavior
 
-## Transport behaviour
+The package includes:
 
-The default browser mount order is:
+- `createClivlyTransport()` for real Clivly backends
+- `createWebSocketTransport()` for explicit socket wiring
+- `createLoopbackTransport()` for local UI/testing flows
 
-1. use a caller-provided `createTransport`
+The default browser mount behavior is:
+
+1. use a caller-provided `createTransport` when present
 2. otherwise prefer `session.socketUrl`
-3. otherwise fall back to `socketUrlTemplate`
+3. otherwise fall back to `socketUrlTemplate` when provided
+
+## Build outputs
+
+The package currently produces:
 
-## Host-side session route
+- `dist/index.*`
+- `dist/browser.*`
+- `dist/browser-mount.*`
+- `dist/widget.global.js`
 
-The widget talks to your backend, not directly to Clivly. Mount the session
-handler from the SDK on your own origin:
+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:
 
 ```ts
 import { createChatSessionHandler } from "clivly/sdk";
@@ -156,23 +201,10 @@ export const POST = createChatSessionHandler({
 });
 ```
 
-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
+`@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.
 
-MIT
+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`.

package/package.json

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