@smooai/smooth-operator 0.1.0 → 0.3.0

package/src/react/response.ts

@@ -0,0 +1,57 @@
+/**
+ * Defensive readers for the terminal `eventual_response` payload.
+ *
+ * These mirror the widget's internal helpers: the server's response envelope and
+ * citation list are optional and back-compatible, so we tolerate their total
+ * absence, non-array shapes, and missing fields rather than letting a slightly
+ * different server break rendering.
+ */
+import type { Citation } from '../types.js';
+
+/** Pull the final assistant text out of an `eventual_response` data payload. */
+export function extractFinalText(response: unknown): string | null {
+    if (!response || typeof response !== 'object') return null;
+    const r = response as { responseParts?: unknown };
+    if (Array.isArray(r.responseParts)) {
+        return r.responseParts.filter((p): p is string => typeof p === 'string').join('\n\n');
+    }
+    return null;
+}
+
+/** Pull the grounding {@link Citation}s out of a terminal `eventual_response`'s inner data. */
+export function extractCitations(inner: unknown): Citation[] {
+    if (!inner || typeof inner !== 'object') return [];
+    const raw = (inner as { citations?: unknown }).citations;
+    if (!Array.isArray(raw)) return [];
+    const out: Citation[] = [];
+    for (const c of raw) {
+        if (!c || typeof c !== 'object') continue;
+        const obj = c as Record<string, unknown>;
+        const id = typeof obj.id === 'string' ? obj.id : '';
+        const title = typeof obj.title === 'string' ? obj.title : id || 'Source';
+        const snippet = typeof obj.snippet === 'string' ? obj.snippet : '';
+        const url = typeof obj.url === 'string' && obj.url ? obj.url : undefined;
+        const score = typeof obj.score === 'number' ? obj.score : 0;
+        out.push({ id, title, snippet, score, url });
+    }
+    return out;
+}
+
+/**
+ * Only `http(s)` URLs become anchor hrefs. Mirrors the widget's `safeHttpUrl`
+ * XSS guard so a `javascript:`/`data:` citation URL can never become a live link.
+ */
+export function safeHttpUrl(url: string | undefined): string | undefined {
+    if (!url) return undefined;
+    try {
+        const parsed = new URL(url, 'http://invalid.local');
+        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            // Reject the sentinel base — only keep genuinely absolute http(s) URLs.
+            if (!/^https?:/i.test(url)) return undefined;
+            return url;
+        }
+    } catch {
+        return undefined;
+    }
+    return undefined;
+}

package/src/react/styles.css

@@ -0,0 +1,231 @@
+/*
+ * smooth-operator-react default stylesheet.
+ *
+ * Import once in your app:
+ *   import '@smooai/smooth-operator/react/styles.css';
+ *
+ * EVERYTHING is driven by `--smooth-*` CSS custom properties declared on the
+ * `.smooth-chat` root (NOT `:root`, so nothing leaks into your page). Retheme by
+ * overriding any of them — in plain CSS, in a Tailwind `@layer base`, with
+ * `theme()` tokens, via a `prefers-color-scheme` block, or per-instance with the
+ * `<SmoothChat theme={…}>` prop (which sets these inline). You can also restyle
+ * the `.smooth-chat__*` classes directly; treat this file as a starting point.
+ */
+
+.smooth-chat {
+    /* ---- Themeable tokens (override these) ---- */
+    --smooth-color-text: #0f172a;
+    --smooth-color-bg: #ffffff;
+    --smooth-color-surface: #f8fafc;
+    --smooth-color-primary: #4f46e5;
+    --smooth-color-primary-text: #ffffff;
+    --smooth-color-assistant-bubble: #eef2ff;
+    --smooth-color-assistant-bubble-text: #0f172a;
+    --smooth-color-user-bubble: var(--smooth-color-primary);
+    --smooth-color-user-bubble-text: var(--smooth-color-primary-text);
+    --smooth-color-border: #e2e8f0;
+    --smooth-color-muted: #64748b;
+    --smooth-radius: 12px;
+    --smooth-font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+
+    display: flex;
+    flex-direction: column;
+    background: var(--smooth-color-bg);
+    color: var(--smooth-color-text);
+    border: 1px solid var(--smooth-color-border);
+    border-radius: var(--smooth-radius);
+    overflow: hidden;
+    font-family: var(--smooth-font);
+}
+
+.smooth-chat *,
+.smooth-chat *::before,
+.smooth-chat *::after {
+    box-sizing: border-box;
+}
+
+.smooth-chat--panel {
+    width: 100%;
+    max-width: 420px;
+    height: 560px;
+}
+
+.smooth-chat--fullpage {
+    width: 100%;
+    height: 100%;
+    min-height: 100%;
+    max-width: none;
+    border: none;
+    border-radius: 0;
+}
+
+/* ---- Header ---- */
+.smooth-chat__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    padding: 12px 16px;
+    background: var(--smooth-color-primary);
+    color: var(--smooth-color-primary-text);
+}
+.smooth-chat__title {
+    font-weight: 600;
+    font-size: 15px;
+}
+.smooth-chat__status {
+    font-size: 11px;
+    opacity: 0.85;
+}
+.smooth-chat__status--error {
+    opacity: 1;
+    font-weight: 600;
+}
+
+/* ---- Messages ---- */
+.smooth-chat__messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    background: var(--smooth-color-surface);
+}
+
+.smooth-chat__bubble {
+    max-width: 82%;
+    padding: 9px 12px;
+    border-radius: var(--smooth-radius);
+    font-size: 14px;
+    line-height: 1.45;
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+.smooth-chat__bubble--assistant {
+    align-self: flex-start;
+    background: var(--smooth-color-assistant-bubble);
+    color: var(--smooth-color-assistant-bubble-text);
+    border-bottom-left-radius: 4px;
+}
+.smooth-chat__bubble--user {
+    align-self: flex-end;
+    background: var(--smooth-color-user-bubble);
+    color: var(--smooth-color-user-bubble-text);
+    border-bottom-right-radius: 4px;
+}
+.smooth-chat__greeting {
+    opacity: 0.85;
+    font-style: italic;
+}
+
+.smooth-chat__cursor::after {
+    content: '▋';
+    margin-left: 1px;
+    animation: smooth-chat-blink 1s steps(2, start) infinite;
+}
+@keyframes smooth-chat-blink {
+    to {
+        visibility: hidden;
+    }
+}
+
+/* ---- Sources / citations ---- */
+.smooth-chat__sources {
+    align-self: flex-start;
+    max-width: 82%;
+    margin-top: -4px;
+    font-size: 12.5px;
+    color: var(--smooth-color-muted);
+}
+.smooth-chat__sources summary {
+    cursor: pointer;
+    font-weight: 600;
+    list-style: none;
+    user-select: none;
+    padding: 2px 0;
+}
+.smooth-chat__sources summary::-webkit-details-marker {
+    display: none;
+}
+.smooth-chat__sources summary::before {
+    content: '▸';
+    display: inline-block;
+    margin-right: 6px;
+    transition: transform 0.15s ease;
+}
+.smooth-chat__sources details[open] summary::before {
+    transform: rotate(90deg);
+}
+.smooth-chat__sources ol {
+    margin: 6px 0 0;
+    padding-left: 0;
+    list-style: none;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+.smooth-chat__sources li {
+    border-left: 2px solid var(--smooth-color-primary);
+    padding-left: 10px;
+}
+.smooth-chat__source-title {
+    color: var(--smooth-color-primary);
+    text-decoration: none;
+    font-weight: 600;
+    word-break: break-word;
+}
+a.smooth-chat__source-title:hover {
+    text-decoration: underline;
+}
+span.smooth-chat__source-title {
+    color: var(--smooth-color-text);
+    opacity: 0.95;
+}
+.smooth-chat__source-snippet {
+    display: block;
+    margin-top: 2px;
+    opacity: 0.75;
+    line-height: 1.4;
+    white-space: normal;
+}
+
+/* ---- Composer ---- */
+.smooth-chat__composer {
+    display: flex;
+    gap: 8px;
+    padding: 10px;
+    border-top: 1px solid var(--smooth-color-border);
+    background: var(--smooth-color-bg);
+}
+.smooth-chat__input {
+    flex: 1;
+    resize: none;
+    border: 1px solid var(--smooth-color-border);
+    border-radius: calc(var(--smooth-radius) - 4px);
+    padding: 8px 10px;
+    font-family: inherit;
+    font-size: 14px;
+    background: var(--smooth-color-bg);
+    color: var(--smooth-color-text);
+    max-height: 120px;
+    line-height: 1.4;
+}
+.smooth-chat__input:focus {
+    outline: 2px solid var(--smooth-color-primary);
+    outline-offset: -1px;
+}
+.smooth-chat__send {
+    border: none;
+    border-radius: calc(var(--smooth-radius) - 4px);
+    padding: 0 16px;
+    cursor: pointer;
+    background: var(--smooth-color-primary);
+    color: var(--smooth-color-primary-text);
+    font-weight: 600;
+    font-size: 14px;
+}
+.smooth-chat__send:disabled {
+    opacity: 0.5;
+    cursor: default;
+}

package/src/react/theme.ts

@@ -0,0 +1,92 @@
+/**
+ * Theming via CSS custom properties.
+ *
+ * Every color/shape the components use is a `--smooth-*` CSS variable with a
+ * default declared in `styles.css` (scoped to `.smooth-chat`, never `:root`, so
+ * it can't leak into the host page). There are three ways to retheme, in order
+ * of precedence (later wins):
+ *
+ *   1. **Your own CSS / Tailwind.** Override the variables on `.smooth-chat`
+ *      (or any ancestor), e.g. in a Tailwind `@layer base` block:
+ *        .smooth-chat { --smooth-color-primary: theme(colors.indigo.600); }
+ *      Because they're plain CSS variables, `theme()`, design tokens, and
+ *      light/dark media queries all just work — no build coupling to this package.
+ *
+ *   2. **A `theme` prop** on `<SmoothChat>` (or `themeToStyle(theme)` spread onto
+ *      any element you render the hook into). This sets the variables inline, so
+ *      it wins over stylesheet rules and is the easiest per-instance override.
+ *
+ *   3. **Inline `style`** on the element, for one-off tweaks.
+ *
+ * Keys intentionally match `@smooai/chat-widget`'s `ChatWidgetTheme` so a brand
+ * palette ports between the web-component widget and these React components
+ * unchanged.
+ */
+import type { CSSProperties } from 'react';
+
+export interface ChatTheme {
+    /** Foreground text color. → `--smooth-color-text` */
+    text?: string;
+    /** Outer surface / page background. → `--smooth-color-bg` */
+    background?: string;
+    /** Panel (message column) background. → `--smooth-color-surface` */
+    surface?: string;
+    /** Primary accent (header, send button, user bubble). → `--smooth-color-primary` */
+    primary?: string;
+    /** Text rendered on top of `primary`. → `--smooth-color-primary-text` */
+    primaryText?: string;
+    /** Assistant bubble background. → `--smooth-color-assistant-bubble` */
+    assistantBubble?: string;
+    /** Assistant bubble text. → `--smooth-color-assistant-bubble-text` */
+    assistantBubbleText?: string;
+    /** User bubble background (defaults to `primary`). → `--smooth-color-user-bubble` */
+    userBubble?: string;
+    /** User bubble text (defaults to `primaryText`). → `--smooth-color-user-bubble-text` */
+    userBubbleText?: string;
+    /** Border / divider color. → `--smooth-color-border` */
+    border?: string;
+    /** Secondary / muted text (status, snippets). → `--smooth-color-muted` */
+    muted?: string;
+    /** Corner radius for bubbles, inputs, the panel. → `--smooth-radius` */
+    radius?: string;
+    /** Font family for the whole surface. → `--smooth-font` */
+    fontFamily?: string;
+}
+
+/** Map each `ChatTheme` key to its CSS custom property name. */
+const VAR_BY_KEY: Record<keyof ChatTheme, string> = {
+    text: '--smooth-color-text',
+    background: '--smooth-color-bg',
+    surface: '--smooth-color-surface',
+    primary: '--smooth-color-primary',
+    primaryText: '--smooth-color-primary-text',
+    assistantBubble: '--smooth-color-assistant-bubble',
+    assistantBubbleText: '--smooth-color-assistant-bubble-text',
+    userBubble: '--smooth-color-user-bubble',
+    userBubbleText: '--smooth-color-user-bubble-text',
+    border: '--smooth-color-border',
+    muted: '--smooth-color-muted',
+    radius: '--smooth-radius',
+    fontFamily: '--smooth-font',
+};
+
+/**
+ * Turn a {@link ChatTheme} into a `style` object of CSS custom properties.
+ * Only keys you set are emitted; everything else falls back to the defaults in
+ * `styles.css`. Spread it onto the root element:
+ *
+ * ```tsx
+ * <div className="smooth-chat" style={themeToStyle({ primary: '#4f46e5' })}>…</div>
+ * ```
+ */
+export function themeToStyle(theme: ChatTheme | undefined): CSSProperties {
+    const style: Record<string, string> = {};
+    if (!theme) return style as CSSProperties;
+    for (const key of Object.keys(theme) as (keyof ChatTheme)[]) {
+        const value = theme[key];
+        if (typeof value === 'string' && value.length > 0) {
+            style[VAR_BY_KEY[key]] = value;
+        }
+    }
+    return style as CSSProperties;
+}

package/src/react/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared types for the React bindings.
+ *
+ * The message + citation shapes mirror `@smooai/chat-widget`'s
+ * `ConversationController` exactly, so the two presentation layers stay
+ * interchangeable over the same protocol client.
+ */
+import type { Citation } from '../types.js';
+
+export type { Citation };
+
+export type Role = 'user' | 'assistant';
+
+/** A single rendered chat message. Assistant messages grow as tokens stream in. */
+export interface ChatMessage {
+    id: string;
+    role: Role;
+    /** Accumulated text (assistant messages grow as `stream_token` events arrive). */
+    text: string;
+    /** True while an assistant message is still streaming. */
+    streaming: boolean;
+    /** Grounding sources, present only when the terminal `eventual_response` carried any. */
+    citations?: Citation[];
+}
+
+/** Connection lifecycle of a conversation. */
+export type ConnectionStatus = 'idle' | 'connecting' | 'ready' | 'error' | 'closed';

package/src/react/use-conversation.ts

@@ -0,0 +1,203 @@
+/**
+ * useConversation — the headless core of the React bindings.
+ *
+ * This hook owns the entire conversation lifecycle (connect → session → stream)
+ * and exposes nothing but state + actions, so you can render a completely custom
+ * UI with zero styling opinions from this package. `<SmoothChat>` and the parts
+ * components are thin views over exactly this hook.
+ *
+ * It is the React analogue of the widget's `ConversationController`: same wire
+ * flow, same defensive payload reading, but message state lives in React so your
+ * components re-render on every streamed token.
+ */
+import { ProtocolError, SmoothAgentClient } from '../client.js';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { extractCitations, extractFinalText } from './response.js';
+import type { ChatMessage, ConnectionStatus } from './types.js';
+
+export interface UseConversationOptions {
+    /** WebSocket endpoint, e.g. `wss://your-host/ws`. Ignored if `client` is given. */
+    url?: string;
+    /**
+     * Bring your own pre-constructed {@link SmoothAgentClient} (e.g. one created by
+     * a {@link SmoothOperatorProvider} and shared, or one with a custom transport
+     * for tests). When provided, the hook does NOT own the client's lifecycle —
+     * it won't disconnect it on unmount.
+     */
+    client?: SmoothAgentClient;
+    /** UUID of the agent to converse with. */
+    agentId: string;
+    /** Optional display name for the user participant. */
+    userName?: string;
+    /** Optional email for the user participant. */
+    userEmail?: string;
+    /**
+     * Short-lived auth token for BYO-auth deployments. Appended to the WS URL as
+     * `?token=…` (browsers can't set WebSocket headers), which the server reads
+     * into the request `Principal` / `AccessContext`. Ignored if `client` is given.
+     */
+    authToken?: string;
+    /** Connect automatically on mount. Default `true`. */
+    autoConnect?: boolean;
+    /** Message shown in the assistant bubble when the connection fails mid-turn. */
+    connectionErrorMessage?: string;
+}
+
+export interface UseConversationResult {
+    /** Current connection lifecycle state. */
+    status: ConnectionStatus;
+    /** The ordered message list (re-renders on every streamed token). */
+    messages: ChatMessage[];
+    /** Last error message, or `null`. */
+    error: string | null;
+    /** The active session id once a session has been created. */
+    sessionId: string | null;
+    /** Open the transport + create a conversation session. Idempotent. */
+    connect: () => Promise<void>;
+    /** Submit a user message and stream the assistant reply into `messages`. */
+    send: (text: string) => Promise<void>;
+    /** Tear down the client (only if this hook owns it) and reset to `closed`. */
+    disconnect: () => void;
+}
+
+/** Append `?token=` / `&token=` to a WS URL for BYO-auth. */
+function withToken(url: string, token: string | undefined): string {
+    if (!token) return url;
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}token=${encodeURIComponent(token)}`;
+}
+
+export function useConversation(options: UseConversationOptions): UseConversationResult {
+    const { url, client: externalClient, agentId, userName, userEmail, authToken, autoConnect = true, connectionErrorMessage } = options;
+
+    const [status, setStatus] = useState<ConnectionStatus>('idle');
+    const [messages, setMessages] = useState<ChatMessage[]>([]);
+    const [error, setError] = useState<string | null>(null);
+
+    // Mutable mirrors so streaming token deltas don't fight React's batching: we
+    // mutate in place, then publish an immutable snapshot via setMessages.
+    const messagesRef = useRef<ChatMessage[]>([]);
+    const clientRef = useRef<SmoothAgentClient | null>(null);
+    const ownsClientRef = useRef(false);
+    const sessionIdRef = useRef<string | null>(null);
+    const seqRef = useRef(0);
+    const statusRef = useRef<ConnectionStatus>('idle');
+
+    const setStatusBoth = useCallback((next: ConnectionStatus, detail?: string) => {
+        statusRef.current = next;
+        setStatus(next);
+        if (next === 'error' && detail) setError(detail);
+        if (next === 'ready' || next === 'connecting') setError(null);
+    }, []);
+
+    const nextId = useCallback((prefix: string) => {
+        seqRef.current += 1;
+        return `${prefix}-${seqRef.current}-${Date.now().toString(36)}`;
+    }, []);
+
+    const publish = useCallback(() => {
+        setMessages(messagesRef.current.map((m) => ({ ...m })));
+    }, []);
+
+    const connect = useCallback(async () => {
+        if (statusRef.current === 'connecting' || statusRef.current === 'ready') return;
+        setStatusBoth('connecting');
+        try {
+            let client = externalClient ?? clientRef.current;
+            if (!client) {
+                if (!url) throw new Error('useConversation requires either `url` or `client`');
+                client = new SmoothAgentClient({ url: withToken(url, authToken) });
+                ownsClientRef.current = true;
+                await client.connect();
+            } else if (client === externalClient) {
+                ownsClientRef.current = false;
+            }
+            clientRef.current = client;
+            const session = await client.createConversationSession({ agentId, userName, userEmail });
+            sessionIdRef.current = session.sessionId;
+            setStatusBoth('ready');
+        } catch (err) {
+            setStatusBoth('error', err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+    }, [externalClient, url, authToken, agentId, userName, userEmail, setStatusBoth]);
+
+    const send = useCallback(
+        async (text: string) => {
+            const trimmed = text.trim();
+            if (!trimmed) return;
+            if (!clientRef.current || !sessionIdRef.current || statusRef.current !== 'ready') {
+                await connect();
+            }
+            const client = clientRef.current;
+            const sessionId = sessionIdRef.current;
+            if (!client || !sessionId) throw new Error('Conversation is not connected');
+
+            messagesRef.current.push({ id: nextId('u'), role: 'user', text: trimmed, streaming: false });
+            const assistant: ChatMessage = { id: nextId('a'), role: 'assistant', text: '', streaming: true };
+            messagesRef.current.push(assistant);
+            publish();
+
+            try {
+                const turn = client.sendMessage({ sessionId, message: trimmed, stream: true });
+                for await (const event of turn) {
+                    if (event.type === 'stream_token') {
+                        const token = event.token ?? event.data?.token ?? '';
+                        if (token) {
+                            assistant.text += token;
+                            publish();
+                        }
+                    }
+                }
+                const final = await turn;
+                const inner = final.data?.data;
+                const finalText = extractFinalText(inner?.response);
+                if (finalText && finalText.length > assistant.text.length) assistant.text = finalText;
+                if (!assistant.text) assistant.text = '(no response)';
+                const citations = extractCitations(inner);
+                if (citations.length > 0) assistant.citations = citations;
+                assistant.streaming = false;
+                publish();
+            } catch (err) {
+                assistant.streaming = false;
+                const message =
+                    err instanceof ProtocolError
+                        ? `Error: ${err.message}`
+                        : (connectionErrorMessage ?? "We couldn't reach the chat. Please try again in a moment.");
+                assistant.text = assistant.text ? `${assistant.text}\n\n${message}` : message;
+                publish();
+                setStatusBoth('error', err instanceof Error ? err.message : String(err));
+            }
+        },
+        [connect, nextId, publish, connectionErrorMessage, setStatusBoth],
+    );
+
+    const disconnect = useCallback(() => {
+        if (ownsClientRef.current) clientRef.current?.disconnect('conversation closed');
+        clientRef.current = externalClient ?? null;
+        sessionIdRef.current = null;
+        setStatusBoth('closed');
+    }, [externalClient, setStatusBoth]);
+
+    // Auto-connect once on mount; tear down only the client we own.
+    useEffect(() => {
+        let cancelled = false;
+        if (autoConnect) {
+            connect().catch(() => {
+                /* surfaced via status/error */
+            });
+        }
+        return () => {
+            cancelled = true;
+            void cancelled;
+            if (ownsClientRef.current) {
+                clientRef.current?.disconnect('component unmounted');
+                clientRef.current = null;
+                ownsClientRef.current = false;
+            }
+        };
+        // Connect identity changes when its inputs change; re-running re-establishes the session.
+    }, [autoConnect, connect]);
+
+    return { status, messages, error, sessionId: sessionIdRef.current, connect, send, disconnect };
+}