@smooai/smooth-operator 0.1.0 → 0.2.0

package/dist/widget/standalone.js

@@ -0,0 +1,15 @@
+import { defineChatWidget, mountChatWidget, mountFullPageChat, SmoothAgentChatElement } from './element.js';
+defineChatWidget();
+export { defineChatWidget, mountChatWidget, mountFullPageChat, SmoothAgentChatElement };
+/** Convenience alias matching the global API surface (`SmoothAgentChat.mount`). */
+export function mount(config, target) {
+    return mountChatWidget(config, target);
+}
+/**
+ * Full-page convenience alias (`SmoothAgentChat.mountFullPage`): mounts the chat
+ * in `mode: "fullpage"` so it fills its container/viewport with no launcher.
+ */
+export function mountFullPage(config, target) {
+    return mountFullPageChat(config, target);
+}
+//# sourceMappingURL=standalone.js.map

package/dist/widget/standalone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.js","sourceRoot":"","sources":["../../src/widget/standalone.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE5G,gBAAgB,EAAE,CAAC;AAEnB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;AAExF,mFAAmF;AACnF,MAAM,UAAU,KAAK,CAAC,MAAwB,EAAE,MAAoB;IAChE,OAAO,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAsC,EAAE,MAAoB;IACtF,OAAO,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/widget/styles.d.ts

@@ -0,0 +1,12 @@
+import type { ChatWidgetMode, ChatWidgetTheme } from './config.js';
+/**
+ * Render the widget's scoped stylesheet. All theme values are injected as CSS
+ * custom properties on `:host` so they can be overridden per-instance and so the
+ * styles below stay static. Kept deliberately framework-light — no Tailwind, no
+ * runtime CSS-in-JS; just a string the web component drops into its shadow root.
+ *
+ * `mode` switches the host positioning + panel sizing between the floating
+ * popover (default) and the full-page layout (fills its container/viewport).
+ */
+export declare function buildStyles(theme: Required<ChatWidgetTheme>, mode?: ChatWidgetMode): string;
+//# sourceMappingURL=styles.d.ts.map

package/dist/widget/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/widget/styles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,GAAE,cAA0B,GAAG,MAAM,CA6PtG"}

package/dist/widget/styles.js

@@ -0,0 +1,262 @@
+/**
+ * Render the widget's scoped stylesheet. All theme values are injected as CSS
+ * custom properties on `:host` so they can be overridden per-instance and so the
+ * styles below stay static. Kept deliberately framework-light — no Tailwind, no
+ * runtime CSS-in-JS; just a string the web component drops into its shadow root.
+ *
+ * `mode` switches the host positioning + panel sizing between the floating
+ * popover (default) and the full-page layout (fills its container/viewport).
+ */
+export function buildStyles(theme, mode = 'popover') {
+    return `
+:host {
+    --sac-text: ${theme.text};
+    --sac-bg: ${theme.background};
+    --sac-primary: ${theme.primary};
+    --sac-primary-text: ${theme.primaryText};
+    --sac-assistant-bubble: ${theme.assistantBubble};
+    --sac-assistant-bubble-text: ${theme.assistantBubbleText};
+    --sac-user-bubble: ${theme.userBubble};
+    --sac-user-bubble-text: ${theme.userBubbleText};
+    --sac-border: ${theme.border};
+
+    ${mode === 'fullpage'
+        ? `/* Full-page: fill the host's box (the element should be sized by its
+       container, or it falls back to filling the viewport). */
+    display: block;
+    position: relative;
+    width: 100%;
+    height: 100%;
+    min-height: 100vh;`
+        : `/* Popover: float in the bottom-right corner. */
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    z-index: 2147483000;`}
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+}
+
+* { box-sizing: border-box; }
+
+.launcher {
+    width: 56px;
+    height: 56px;
+    border-radius: 50%;
+    border: none;
+    cursor: pointer;
+    background: var(--sac-primary);
+    color: var(--sac-primary-text);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 24px;
+    transition: transform 0.15s ease;
+}
+.launcher:hover { transform: scale(1.05); }
+
+.panel {
+    width: 360px;
+    max-width: calc(100vw - 40px);
+    height: 520px;
+    max-height: calc(100vh - 40px);
+    display: flex;
+    flex-direction: column;
+    background: var(--sac-bg);
+    color: var(--sac-text);
+    border: 1px solid var(--sac-border);
+    border-radius: 14px;
+    overflow: hidden;
+    box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
+}
+
+/* Full-page: the panel becomes the whole surface — no floating box, no shadow,
+   no rounded corners; it fills the host. */
+.panel.fullpage {
+    width: 100%;
+    height: 100%;
+    min-height: 100vh;
+    max-width: none;
+    max-height: none;
+    border: none;
+    border-radius: 0;
+    box-shadow: none;
+}
+
+.header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 14px;
+    background: var(--sac-primary);
+    color: var(--sac-primary-text);
+}
+.header .brand { display: flex; align-items: center; gap: 10px; min-width: 0; }
+.header .logo { height: 24px; width: auto; display: block; }
+.header .title { font-weight: 600; font-size: 15px; }
+.header .status { font-size: 11px; opacity: 0.85; }
+.header .powered {
+    font-size: 10px;
+    opacity: 0.7;
+    letter-spacing: 0.02em;
+}
+.header .close {
+    background: transparent;
+    border: none;
+    color: inherit;
+    cursor: pointer;
+    font-size: 18px;
+    line-height: 1;
+    padding: 4px;
+}
+
+/* Full-page header: taller, logo-led, centered max-width content row. */
+.panel.fullpage .header { padding: 14px 20px; }
+.panel.fullpage .logo { height: 30px; }
+
+.messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+}
+
+.bubble {
+    max-width: 80%;
+    padding: 9px 12px;
+    border-radius: 12px;
+    font-size: 14px;
+    line-height: 1.4;
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+.bubble.assistant {
+    align-self: flex-start;
+    background: var(--sac-assistant-bubble);
+    color: var(--sac-assistant-bubble-text);
+    border-bottom-left-radius: 4px;
+}
+.bubble.user {
+    align-self: flex-end;
+    background: var(--sac-user-bubble);
+    color: var(--sac-user-bubble-text);
+    border-bottom-right-radius: 4px;
+}
+.bubble.greeting { opacity: 0.85; font-style: italic; }
+
+/* Full-page: center the conversation in a readable column and let bubbles
+   breathe a little wider. */
+.panel.fullpage .messages {
+    padding: 24px 20px;
+    align-items: stretch;
+}
+.panel.fullpage .messages > * {
+    width: 100%;
+    max-width: 760px;
+    margin-left: auto;
+    margin-right: auto;
+}
+.panel.fullpage .bubble { max-width: 100%; }
+.panel.fullpage .bubble.user { align-self: flex-end; max-width: 80%; margin-right: auto; }
+.panel.fullpage .bubble.assistant { align-self: flex-start; max-width: 100%; }
+
+/* Sources panel — rendered under an assistant bubble whose terminal
+   eventual_response carried citations. */
+.sources {
+    align-self: flex-start;
+    max-width: 80%;
+    margin-top: -4px;
+    font-size: 12.5px;
+    color: var(--sac-text);
+}
+.panel.fullpage .sources { max-width: 100%; }
+.sources details { background: transparent; }
+.sources summary {
+    cursor: pointer;
+    font-weight: 600;
+    opacity: 0.85;
+    list-style: none;
+    user-select: none;
+    padding: 2px 0;
+}
+.sources summary::-webkit-details-marker { display: none; }
+.sources summary::before {
+    content: '▸';
+    display: inline-block;
+    margin-right: 6px;
+    transition: transform 0.15s ease;
+}
+.sources details[open] summary::before { transform: rotate(90deg); }
+.sources ol {
+    margin: 6px 0 0;
+    padding-left: 0;
+    list-style: none;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+.sources li {
+    border-left: 2px solid var(--sac-primary);
+    padding-left: 10px;
+}
+.sources .src-title {
+    color: var(--sac-primary);
+    text-decoration: none;
+    font-weight: 600;
+    word-break: break-word;
+}
+.sources a.src-title:hover { text-decoration: underline; }
+.sources span.src-title { color: var(--sac-text); opacity: 0.95; }
+.sources .src-snippet {
+    display: block;
+    margin-top: 2px;
+    opacity: 0.7;
+    line-height: 1.4;
+    white-space: normal;
+}
+
+.cursor::after {
+    content: '▋';
+    margin-left: 1px;
+    animation: sac-blink 1s steps(2, start) infinite;
+}
+@keyframes sac-blink { to { visibility: hidden; } }
+
+.composer {
+    display: flex;
+    gap: 8px;
+    padding: 10px;
+    border-top: 1px solid var(--sac-border);
+}
+.composer textarea {
+    flex: 1;
+    resize: none;
+    border: 1px solid var(--sac-border);
+    border-radius: 8px;
+    padding: 8px 10px;
+    font-family: inherit;
+    font-size: 14px;
+    background: transparent;
+    color: var(--sac-text);
+    max-height: 96px;
+    line-height: 1.4;
+}
+.composer textarea:focus { outline: 1px solid var(--sac-primary); }
+.composer button {
+    border: none;
+    border-radius: 8px;
+    padding: 0 14px;
+    cursor: pointer;
+    background: var(--sac-primary);
+    color: var(--sac-primary-text);
+    font-weight: 600;
+    font-size: 14px;
+}
+.composer button:disabled { opacity: 0.5; cursor: default; }
+
+.hidden { display: none !important; }
+`;
+}
+//# sourceMappingURL=styles.js.map

package/dist/widget/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/widget/styles.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgC,EAAE,OAAuB,SAAS;IAC1F,OAAO;;kBAEO,KAAK,CAAC,IAAI;gBACZ,KAAK,CAAC,UAAU;qBACX,KAAK,CAAC,OAAO;0BACR,KAAK,CAAC,WAAW;8BACb,KAAK,CAAC,eAAe;mCAChB,KAAK,CAAC,mBAAmB;yBACnC,KAAK,CAAC,UAAU;8BACX,KAAK,CAAC,cAAc;oBAC9B,KAAK,CAAC,MAAM;;MAGxB,IAAI,KAAK,UAAU;QACf,CAAC,CAAC;;;;;;uBAMS;QACX,CAAC,CAAC;;;;yBAKV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiOH,CAAC;AACF,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smooai/smooth-operator",
-  "version": "0.1.0",
-  "description": "TypeScript protocol types and native WebSocket client for the smooth-operator protocol. Generated from the language-neutral JSON Schemas in spec/.",
+  "version": "0.2.0",
+  "description": "TypeScript SDK for the smooth-operator WebSocket protocol: the native client (`.`), React bindings (`./react`), and the embeddable web-component chat widget (`./widget`). Generated from the language-neutral JSON Schemas in spec/.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -18,7 +18,17 @@
     "./validate": {
       "types": "./dist/validate.d.ts",
       "import": "./dist/validate.js"
-    }
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./react/styles.css": "./src/react/styles.css",
+    "./widget": {
+      "types": "./dist/widget/index.d.ts",
+      "import": "./dist/widget/index.js"
+    },
+    "./widget/standalone": "./dist/widget/chat-widget.iife.js"
   },
   "publishConfig": {
     "access": "public"
@@ -36,7 +46,12 @@
     "client",
     "ai",
     "agent",
-    "streaming"
+    "streaming",
+    "react",
+    "chat",
+    "widget",
+    "web-component",
+    "rag"
   ],
   "files": [
     "dist",
@@ -46,20 +61,43 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1"
   },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.7.3",
+    "@playwright/test": "^1.49.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
     "@types/node": "^25.9.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.1",
     "json-schema-to-typescript": "^15.0.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsdown": "^0.22.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "typecheck:e2e": "tsc --noEmit -p tsconfig.e2e.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts"
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:widget": "playwright test --project=chromium"
   }
 }

package/src/react/components/SmoothChat.tsx

@@ -0,0 +1,57 @@
+/**
+ * <SmoothChat> — the opinionated, drop-in chat surface.
+ *
+ * It wires `useConversation` to the presentational parts and applies the
+ * `.smooth-chat` root class whose styling is 100% CSS-variable-driven. Theme it
+ * any of three ways (see `theme.ts`): override `--smooth-*` in your CSS/Tailwind,
+ * pass a `theme` prop (sets the variables inline), or restyle the
+ * `smooth-chat__*` classes outright.
+ *
+ * Need full control? Skip this component and build your own view over
+ * `useConversation` + the exported parts. This is just the batteries-included path.
+ *
+ * Remember to import the stylesheet once in your app:
+ *   import '@smooai/smooth-operator/react/styles.css';
+ */
+import { themeToStyle, type ChatTheme } from '../theme.js';
+import { useConversation, type UseConversationOptions } from '../use-conversation.js';
+import { Composer, ConnectionStatusLabel, MessageList } from './parts.js';
+
+export interface SmoothChatProps extends UseConversationOptions {
+    /** Header label for the agent. Default "Assistant". */
+    agentName?: string;
+    /** Greeting rendered before any messages. */
+    greeting?: string;
+    /** Placeholder for the input. */
+    placeholder?: string;
+    /** Per-instance theme overrides (sets `--smooth-*` inline; wins over stylesheet rules). */
+    theme?: ChatTheme;
+    /** Show the small connection-status label in the header. Default `true`. */
+    showStatus?: boolean;
+    /** Extra class names on the `.smooth-chat` root (e.g. Tailwind layout utilities). */
+    className?: string;
+    /** Layout: `panel` (bordered card) or `fullpage` (fills its container). Default `panel`. */
+    layout?: 'panel' | 'fullpage';
+}
+
+export function SmoothChat(props: SmoothChatProps) {
+    const { agentName = 'Assistant', greeting, placeholder, theme, showStatus = true, className, layout = 'panel', ...conversationOptions } = props;
+
+    const { status, messages, send } = useConversation(conversationOptions);
+    const busy = messages.some((m) => m.streaming);
+
+    return (
+        <div
+            className={['smooth-chat', `smooth-chat--${layout}`, className].filter(Boolean).join(' ')}
+            style={themeToStyle(theme)}
+            data-status={status}
+        >
+            <header className="smooth-chat__header">
+                <span className="smooth-chat__title">{agentName}</span>
+                {showStatus ? <ConnectionStatusLabel status={status} /> : null}
+            </header>
+            <MessageList messages={messages} greeting={greeting} />
+            <Composer onSend={(text) => void send(text)} disabled={status === 'connecting' || busy} placeholder={placeholder} />
+        </div>
+    );
+}

package/src/react/components/parts.tsx

@@ -0,0 +1,141 @@
+/**
+ * Presentational building blocks.
+ *
+ * Each part is a thin, styling-light view over the data `useConversation`
+ * produces. They render semantic markup with `smooth-chat__*` class names whose
+ * styling lives entirely in `styles.css` and is driven by `--smooth-*` CSS
+ * variables — so retheming is CSS, never prop-drilling. Every part also forwards
+ * `className` so you can layer Tailwind utilities on top, and you can ignore
+ * these entirely and render the hook's state yourself.
+ */
+import { useState, type FormEvent, type KeyboardEvent } from 'react';
+import { safeHttpUrl } from '../response.js';
+import type { ChatMessage, Citation, ConnectionStatus } from '../types.js';
+
+function cx(...parts: (string | false | undefined)[]): string {
+    return parts.filter(Boolean).join(' ');
+}
+
+/** A list of grounding sources rendered under an assistant bubble. */
+export function Citations({ citations, className }: { citations: Citation[]; className?: string }) {
+    if (!citations.length) return null;
+    return (
+        <div className={cx('smooth-chat__sources', className)}>
+            <details>
+                <summary>
+                    {citations.length} source{citations.length === 1 ? '' : 's'}
+                </summary>
+                <ol>
+                    {citations.map((c) => {
+                        const href = safeHttpUrl(c.url);
+                        return (
+                            <li key={c.id || c.title}>
+                                {href ? (
+                                    <a className="smooth-chat__source-title" href={href} target="_blank" rel="noreferrer noopener">
+                                        {c.title}
+                                    </a>
+                                ) : (
+                                    <span className="smooth-chat__source-title">{c.title}</span>
+                                )}
+                                {c.snippet ? <span className="smooth-chat__source-snippet">{c.snippet}</span> : null}
+                            </li>
+                        );
+                    })}
+                </ol>
+            </details>
+        </div>
+    );
+}
+
+/** A single message bubble (+ its citations + streaming cursor). */
+export function MessageBubble({ message, className }: { message: ChatMessage; className?: string }) {
+    return (
+        <>
+            <div className={cx('smooth-chat__bubble', `smooth-chat__bubble--${message.role}`, message.streaming && 'smooth-chat__bubble--streaming', className)}>
+                {message.text}
+                {message.streaming ? <span className="smooth-chat__cursor" aria-hidden="true" /> : null}
+            </div>
+            {message.role === 'assistant' && message.citations?.length ? <Citations citations={message.citations} /> : null}
+        </>
+    );
+}
+
+/** The scrollable message column. Renders an optional greeting before any messages. */
+export function MessageList({ messages, greeting, className }: { messages: ChatMessage[]; greeting?: string; className?: string }) {
+    return (
+        <div className={cx('smooth-chat__messages', className)} role="log" aria-live="polite">
+            {messages.length === 0 && greeting ? <div className="smooth-chat__bubble smooth-chat__bubble--assistant smooth-chat__greeting">{greeting}</div> : null}
+            {messages.map((m) => (
+                <MessageBubble key={m.id} message={m} />
+            ))}
+        </div>
+    );
+}
+
+/** The input row. Calls `onSend` on submit / Enter (Shift+Enter inserts a newline). */
+export function Composer({
+    onSend,
+    disabled,
+    placeholder = 'Type a message…',
+    className,
+}: {
+    onSend: (text: string) => void;
+    disabled?: boolean;
+    placeholder?: string;
+    className?: string;
+}) {
+    const [value, setValue] = useState('');
+
+    const submit = () => {
+        const text = value.trim();
+        if (!text || disabled) return;
+        setValue('');
+        onSend(text);
+    };
+
+    const onSubmit = (e: FormEvent) => {
+        e.preventDefault();
+        submit();
+    };
+
+    const onKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+        if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            submit();
+        }
+    };
+
+    return (
+        <form className={cx('smooth-chat__composer', className)} onSubmit={onSubmit}>
+            <textarea
+                className="smooth-chat__input"
+                value={value}
+                placeholder={placeholder}
+                onChange={(e) => setValue(e.target.value)}
+                onKeyDown={onKeyDown}
+                rows={1}
+                aria-label="Message"
+            />
+            <button className="smooth-chat__send" type="submit" disabled={disabled || value.trim().length === 0}>
+                Send
+            </button>
+        </form>
+    );
+}
+
+const STATUS_LABEL: Record<ConnectionStatus, string> = {
+    idle: 'Idle',
+    connecting: 'Connecting…',
+    ready: 'Online',
+    error: 'Connection error',
+    closed: 'Disconnected',
+};
+
+/** A small connection-status label. */
+export function ConnectionStatusLabel({ status, className }: { status: ConnectionStatus; className?: string }) {
+    return (
+        <span className={cx('smooth-chat__status', `smooth-chat__status--${status}`, className)} aria-live="polite">
+            {STATUS_LABEL[status]}
+        </span>
+    );
+}

package/src/react/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @smooai/smooth-operator/react — React bindings for the smooth-operator
+ * WebSocket protocol.
+ *
+ * Two layers, use whichever you need:
+ *
+ *   • Headless — `useConversation` (+ `SmoothOperatorProvider`) own the whole
+ *     connect → session → stream lifecycle and expose only state + actions. Build
+ *     any UI you like on top; this package imposes zero styling.
+ *
+ *   • Batteries-included — `<SmoothChat>` and the `parts` components render a
+ *     complete, accessible chat surface themed entirely by `--smooth-*` CSS
+ *     variables. Import the stylesheet once:
+ *       import '@smooai/smooth-operator/react/styles.css';
+ *
+ * The protocol client itself lives in `@smooai/smooth-operator`; re-exported here
+ * for convenience so you can construct/share a client without a second import.
+ */
+export { SmoothAgentClient, MessageTurn, ProtocolError, TurnTimeoutError, type SmoothAgentClientOptions } from '../index.js';
+
+export { useConversation, type UseConversationOptions, type UseConversationResult } from './use-conversation.js';
+export { SmoothOperatorProvider, useSmoothOperator, type SmoothOperatorProviderProps, type SmoothOperatorContextValue } from './provider.js';
+
+export { themeToStyle, type ChatTheme } from './theme.js';
+export { safeHttpUrl, extractCitations, extractFinalText } from './response.js';
+
+export { SmoothChat, type SmoothChatProps } from './components/SmoothChat.js';
+export { MessageList, MessageBubble, Citations, Composer, ConnectionStatusLabel } from './components/parts.js';
+
+export type { ChatMessage, ConnectionStatus, Role, Citation } from './types.js';

package/src/react/provider.tsx

@@ -0,0 +1,40 @@
+/**
+ * SmoothOperatorProvider — optional context that owns a single shared
+ * {@link SmoothAgentClient} for a subtree.
+ *
+ * You don't need this to use the hooks (`useConversation` can take a `url`
+ * directly), but a provider is handy when several components share one WS
+ * connection, or when you want to construct the client yourself (custom
+ * transport, auth-token refresh, etc.) and hand it down.
+ */
+import { SmoothAgentClient } from '../client.js';
+import { createContext, createElement, useContext, useMemo, type ReactNode } from 'react';
+
+export interface SmoothOperatorContextValue {
+    client: SmoothAgentClient | null;
+    /** The base WS URL, if the provider was given one (so hooks can construct per-session clients). */
+    url: string | null;
+}
+
+const SmoothOperatorContext = createContext<SmoothOperatorContextValue | null>(null);
+
+export interface SmoothOperatorProviderProps {
+    /** A pre-constructed client to share. Takes precedence over `url`. */
+    client?: SmoothAgentClient;
+    /** A WS URL the provider memoizes a client from, if no `client` is passed. */
+    url?: string;
+    children: ReactNode;
+}
+
+export function SmoothOperatorProvider({ client, url, children }: SmoothOperatorProviderProps) {
+    const value = useMemo<SmoothOperatorContextValue>(() => {
+        if (client) return { client, url: url ?? null };
+        return { client: null, url: url ?? null };
+    }, [client, url]);
+    return createElement(SmoothOperatorContext.Provider, { value }, children);
+}
+
+/** Read the nearest provider value, or `null` if there is no provider. */
+export function useSmoothOperator(): SmoothOperatorContextValue | null {
+    return useContext(SmoothOperatorContext);
+}