@convai/web-widget 0.1.4 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ production** — [step two](#before-you-ship) moves it to your server.
 
 ```html
 <convai-widget character-id="YOUR_CHARACTER_ID" api-key="YOUR_API_KEY"></convai-widget>
-<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.4/v1.js" async></script>
+<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.2.0/v1.js" async></script>
 ```
 
 A launcher bubble appears in the bottom-right corner. Click it: the runtime
@@ -23,7 +23,7 @@ The script tag goes in your HTML shell; the element is ordinary JSX.
 
 ```html
 <!-- index.html -->
-<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.4/v1.js" async></script>
+<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.2.0/v1.js" async></script>
 ```
 
 ```jsx
@@ -33,12 +33,56 @@ The script tag goes in your HTML shell; the element is ordinary JSX.
 In Next.js, use `next/script` with `strategy="afterInteractive"` — it injects a
 classic script tag, which is what the loader needs.
 
-> **Do not `import` this package into an app bundle.** The loader derives the
-> runtime chunk's URL from its own `<script src>`, so a bundled import (or a
-> `<script type="module">`) leaves it with nothing to derive from: the bubble
-> paints and then fails on click with `could not resolve the runtime URL`. Load
-> it from a script tag. The npm package exists so you can self-host `v1.js` and
-> `runtime.js` from your own origin.
+> **Load `v1.js` from a script tag, never from a bundle.** The loader derives
+> the runtime chunk's URL from its own `<script src>`, so a bundled import (or a
+> `<script type="module">`) leaves it nothing to derive from: the bubble paints
+> and then fails on click with `could not resolve the runtime URL`. That applies
+> to the element only. If you are building an app, you probably want the
+> library entries below instead.
+
+## Already using `@convai/web-sdk` or `@convai/embody`?
+
+Then you already have a `ConvaiClient`, and you should not let the element build
+a second one: that is two connections, two conversation histories and two
+billed sessions against the same character, with no error to tell you.
+
+Import the chat UI instead and hand it the client you have. These entries keep
+`@convai/web-sdk`, React and `livekit-client` external, so your bundler links
+one copy of each — the app's own.
+
+**React**
+
+```tsx
+import { useConvaiClient } from '@convai/web-sdk/react'
+import { ConvaiWidget } from '@convai/web-widget/react'
+
+export function Chat() {
+  const client = useConvaiClient({ apiKey: API_KEY, characterId: CHARACTER_ID })
+  return <ConvaiWidget convaiClient={client} />
+}
+```
+
+**No framework**
+
+```ts
+import { ConvaiClient } from '@convai/web-sdk/core'
+import { createConvaiWidget } from '@convai/web-widget/vanilla'
+
+const client = new ConvaiClient({ apiKey: API_KEY, characterId: CHARACTER_ID })
+createConvaiWidget(document.body, { convaiClient: client })
+```
+
+The vanilla entry is hand-written DOM and CSS. It imports no React,
+styled-components or framer-motion, so none of them reach your bundle.
+
+| Entry | What it is | For |
+|---|---|---|
+| `v1.js` (script tag) | the `<convai-widget>` element, SDK bundled in | a page with no build step |
+| `@convai/web-widget/react` | `ConvaiWidget`, `MarkdownRenderer`, `useCharacterInfo` | React apps |
+| `@convai/web-widget/vanilla` | `createConvaiWidget` | apps without a framework |
+
+These moved here from `@convai/web-sdk`, which now creates clients and ships no
+UI. Install `@convai/web-sdk` alongside this package; it is a peer dependency.
 
 ## Before you ship
 
@@ -98,16 +142,16 @@ guide; theming and `::part()` hooks; CSP requirements; and guidance on
 
 ## Versioning
 
-`0.1.4` is a stable release: `npm install @convai/web-widget` and
+`0.2.0` is a stable release: `npm install @convai/web-widget` and
 jsDelivr's unversioned URL both resolve it. Pin the exact version anyway for
 reproducible deploys —
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.1.4/v1.js" async></script>
+<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.2.0/v1.js" async></script>
 ```
 
 ```bash
-npm install @convai/web-widget@0.1.4   # only needed to self-host the two files
+npm install @convai/web-widget@0.2.0   # only needed to self-host the two files
 ```
 
 This package is early, and it bundles a prerelease of `@convai/web-sdk`. The