@smooai/chat-widget 0.3.0

package/src/element.ts

@@ -0,0 +1,563 @@
+/**
+ * `<smooth-agent-chat>` — a framework-light embeddable chat web component.
+ *
+ * A clean, dependency-light web component that preserves a familiar embedding
+ * model — a launcher + popover panel, declarative HTML attributes, and a
+ * programmatic API — while talking to the `@smooai/smooth-operator` protocol
+ * client. The visual layer is the "Aurora Glass" design system (see
+ * {@link buildStyles}): a spring launcher with a live presence pulse, a
+ * glass-depth panel, a gradient brand avatar + status dot, an animated typing
+ * indicator, message rise-in, refined source cards, and an icon composer. Every
+ * color is driven by `--sac-*` custom properties so a host's brand flows through.
+ *
+ * Embedding model:
+ *   <smooth-agent-chat endpoint="ws://localhost:8787/ws" agent-id="…"></smooth-agent-chat>
+ * or programmatically via {@link mountChatWidget}.
+ */
+import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
+import { needsUserInfo, resolveConfig } from './config.js';
+import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController } from './conversation.js';
+import { SMOOTH_LOGO_SVG } from './logo.js';
+import { buildStyles } from './styles.js';
+
+export const ELEMENT_TAG = 'smooth-agent-chat';
+
+const OBSERVED = ['endpoint', 'agent-id', 'agent-name', 'placeholder', 'greeting', 'start-open', 'mode'] as const;
+
+/**
+ * Inline SVG icons (static, trusted strings — never interpolated with user data).
+ * Kept here so the IIFE bundle is self-contained: no icon-font or network fetch.
+ */
+const ICON = {
+    /** Launcher — a speech bubble carrying a spark (chat + AI). */
+    spark: `<svg class="ico" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 3.5c-4.7 0-8.5 3.2-8.5 7.2 0 2.2 1.2 4.2 3 5.5v3.3l3.2-1.7c.7.1 1.5.2 2.3.2 4.7 0 8.5-3.2 8.5-7.3S16.7 3.5 12 3.5Z" fill="currentColor" opacity=".22"/><path d="M13.4 7.2 9 12.6h2.6l-1 4.2 4.4-5.4h-2.6l1-4.2Z" fill="currentColor"/></svg>`,
+    /** Small assistant avatar used beside each assistant message. */
+    bot: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="4.5" y="7.5" width="15" height="11" rx="3.5" stroke="currentColor" stroke-width="1.6"/><path d="M12 4.5v3M8.5 12.2h.01M15.5 12.2h.01" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path d="M9.5 15.4c.7.6 1.5.9 2.5.9s1.8-.3 2.5-.9" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>`,
+    /** Close (collapse panel) — a downward chevron. */
+    close: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="m7 10 5 5 5-5" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+    /** Send — an upward arrow. */
+    send: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 19V6M12 6l-5.5 5.5M12 6l5.5 5.5" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+    /** Sources disclosure caret. */
+    chev: `<svg width="11" height="11" viewBox="0 0 24 24" fill="none"><path d="m9 6 6 6-6 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
+} as const;
+
+/**
+ * Return `url` only if it is a valid absolute `http(s)` URL, else `null`.
+ *
+ * SECURITY: citation URLs originate from indexed content (web / GitHub
+ * connectors), which can be attacker-influenceable. Assigning an arbitrary
+ * string to `<a>.href` allows `javascript:`/`data:`/`vbscript:` URLs that
+ * execute on click — a stored-XSS vector. Only http(s) links are rendered as
+ * anchors; anything else falls back to plain text.
+ */
+export function safeHttpUrl(url: string | undefined | null): string | null {
+    if (!url) return null;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed.href : null;
+    } catch {
+        return null;
+    }
+}
+
+export class SmoothAgentChatElement extends HTMLElement {
+    static get observedAttributes(): readonly string[] {
+        return OBSERVED;
+    }
+
+    private readonly root: ShadowRoot;
+    private controller: ConversationController | null = null;
+    private overrides: Partial<ChatWidgetConfig> = {};
+    private open = false;
+    private messages: ChatMessage[] = [];
+    private status: ConnectionStatus = 'idle';
+    private mounted = false;
+    /** True once the visitor has cleared the pre-chat identity gate (or it's not needed). */
+    private userInfoSatisfied = false;
+    /** True after the visitor has sent their first message (hides starter chips). */
+    private hasSent = false;
+    /** Starter prompts shown as chips in the empty state. */
+    private examplePrompts: string[] = [];
+
+    // Cached DOM refs (populated in render()).
+    private panelEl: HTMLElement | null = null;
+    private launcherEl: HTMLElement | null = null;
+    private messagesEl: HTMLElement | null = null;
+    private statusEl: HTMLElement | null = null;
+    private dotEl: HTMLElement | null = null;
+    private inputEl: HTMLTextAreaElement | null = null;
+    private sendBtn: HTMLButtonElement | null = null;
+
+    constructor() {
+        super();
+        this.root = this.attachShadow({ mode: 'open' });
+    }
+
+    connectedCallback(): void {
+        this.mounted = true;
+        this.render();
+    }
+
+    disconnectedCallback(): void {
+        this.mounted = false;
+        this.controller?.disconnect();
+        this.controller = null;
+    }
+
+    attributeChangedCallback(): void {
+        if (this.mounted) this.render();
+    }
+
+    /**
+     * Programmatically merge config overrides (endpoint, agentId, theme, …). Values
+     * set here take precedence over HTML attributes. Re-renders the widget.
+     */
+    configure(config: Partial<ChatWidgetConfig>): void {
+        this.overrides = { ...this.overrides, ...config };
+        if (config.theme) {
+            this.overrides.theme = { ...(this.overrides.theme ?? {}), ...config.theme };
+        }
+        if (this.mounted) this.render();
+    }
+
+    /** Open the chat panel. */
+    openChat(): void {
+        this.open = true;
+        this.syncOpenState();
+        void this.controller?.connect().catch(() => {});
+    }
+
+    /** Collapse the chat panel back to the launcher. */
+    closeChat(): void {
+        this.open = false;
+        this.syncOpenState();
+    }
+
+    // ─────────────────────────── Config resolution ─────────────────────────────
+
+    private readConfig(): ChatWidgetConfig | null {
+        const endpoint = this.overrides.endpoint ?? this.getAttribute('endpoint') ?? '';
+        const agentId = this.overrides.agentId ?? this.getAttribute('agent-id') ?? '';
+        if (!endpoint || !agentId) return null;
+
+        const theme: ChatWidgetTheme | undefined = this.overrides.theme;
+        const modeAttr = this.getAttribute('mode');
+        const mode: ChatWidgetMode = this.overrides.mode ?? (modeAttr === 'fullpage' ? 'fullpage' : modeAttr === 'popover' ? 'popover' : undefined) ?? 'popover';
+        return {
+            endpoint,
+            mode,
+            agentId,
+            agentName: this.overrides.agentName ?? this.getAttribute('agent-name') ?? undefined,
+            userName: this.overrides.userName,
+            userEmail: this.overrides.userEmail,
+            userPhone: this.overrides.userPhone,
+            placeholder: this.overrides.placeholder ?? this.getAttribute('placeholder') ?? undefined,
+            greeting: this.overrides.greeting ?? this.getAttribute('greeting') ?? undefined,
+            connectionErrorMessage: this.overrides.connectionErrorMessage,
+            startOpen: this.overrides.startOpen ?? this.hasAttribute('start-open'),
+            examplePrompts: this.overrides.examplePrompts,
+            requireName: this.overrides.requireName,
+            requireEmail: this.overrides.requireEmail,
+            requirePhone: this.overrides.requirePhone,
+            allowAnonymous: this.overrides.allowAnonymous,
+            theme,
+        };
+    }
+
+    // ───────────────────────────────── Render ──────────────────────────────────
+
+    private render(): void {
+        const config = this.readConfig();
+        if (!config) {
+            this.root.innerHTML = '';
+            return;
+        }
+        const resolved = resolveConfig(config);
+
+        // (Re)create the controller only when there isn't one yet. Attribute churn
+        // (e.g. theme tweaks) re-renders the view without dropping the session.
+        if (!this.controller) {
+            this.controller = new ConversationController(config, {
+                onMessages: (messages) => {
+                    this.messages = messages;
+                    this.renderMessages(resolved.greeting);
+                },
+                onStatus: (status) => {
+                    this.status = status;
+                    this.renderStatus();
+                    this.renderComposerState();
+                },
+            });
+            if (resolved.startOpen) this.open = true;
+        }
+
+        const fullpage = resolved.mode === 'fullpage';
+        // Full-page mode is always "open" — it fills its container and has no
+        // launcher to toggle.
+        if (fullpage) this.open = true;
+
+        const style = document.createElement('style');
+        style.textContent = buildStyles(resolved.theme, resolved.mode);
+
+        // Header: in full-page mode lead with the Smooth logo in the avatar tile
+        // and a subtle "powered by" tag; in popover mode show a brand-colored
+        // monogram avatar + a compact close (collapse) button.
+        const monogram = escapeHtml((resolved.agentName.trim().charAt(0) || 'A').toUpperCase());
+        const header = fullpage
+            ? `<div class="header">
+                    <div class="avatar"><span class="logo-wrap">${SMOOTH_LOGO_SVG}</span></div>
+                    <div class="meta">
+                        <span class="title">${escapeHtml(resolved.agentName)}</span>
+                        <span class="status"><span class="dot off"></span><span class="status-text"></span></span>
+                    </div>
+                    <span class="powered">powered by smooth-operator</span>
+                </div>`
+            : `<div class="header">
+                    <div class="avatar">${monogram}</div>
+                    <div class="meta">
+                        <span class="title">${escapeHtml(resolved.agentName)}</span>
+                        <span class="status"><span class="dot off"></span><span class="status-text"></span></span>
+                    </div>
+                    <button class="close" aria-label="Close chat">${ICON.close}</button>
+                </div>`;
+
+        // Remember starter prompts for the empty-state chips.
+        this.examplePrompts = resolved.examplePrompts;
+
+        // Gate the conversation behind a pre-chat identity form when required.
+        const gating = needsUserInfo(resolved) && !this.userInfoSatisfied;
+        const field = (name: string, type: string, label: string, autocomplete: string) =>
+            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}" required /></label>`;
+        const prechatHtml = `
+            <div class="prechat">
+                <div class="pc-head">
+                    <div class="pc-title">Before we chat</div>
+                    <div class="pc-sub">A couple details so ${escapeHtml(resolved.agentName)} can help.</div>
+                </div>
+                <form class="pc-form" novalidate>
+                    ${resolved.requireName ? field('name', 'text', 'Name', 'name') : ''}
+                    ${resolved.requireEmail ? field('email', 'email', 'Email', 'email') : ''}
+                    ${resolved.requirePhone ? field('phone', 'tel', 'Phone', 'tel') : ''}
+                    <button type="submit" class="pc-submit">Start chat</button>
+                </form>
+            </div>`;
+        const chatHtml = `
+                <div class="messages"></div>
+                <div class="composer-wrap">
+                    <div class="composer">
+                        <textarea rows="1" placeholder="${escapeHtml(resolved.placeholder)}"></textarea>
+                        <button class="send" type="button" aria-label="Send message">${ICON.send}</button>
+                    </div>
+                    <div class="footer">powered by <b>smooth&#8209;operator</b></div>
+                </div>`;
+
+        const container = document.createElement('div');
+        container.innerHTML = `
+            ${fullpage ? '' : `<button class="launcher" part="launcher" aria-label="Open chat">${ICON.spark}</button>`}
+            <div class="panel${fullpage ? ' fullpage' : ' hidden'}" part="panel" role="${fullpage ? 'region' : 'dialog'}" aria-label="${escapeHtml(resolved.agentName)} chat">
+                ${header}
+                <div class="header-sep"></div>
+                ${gating ? prechatHtml : chatHtml}
+            </div>
+        `;
+
+        // Tag the logo <svg> so styles can size it (the inlined SVG has its own id).
+        const logoSvg = container.querySelector('.logo-wrap svg');
+        if (logoSvg) logoSvg.setAttribute('class', 'logo');
+
+        this.root.replaceChildren(style, container);
+
+        this.launcherEl = container.querySelector('.launcher');
+        this.panelEl = container.querySelector('.panel');
+        this.messagesEl = container.querySelector('.messages');
+        this.statusEl = container.querySelector('.status-text');
+        this.dotEl = container.querySelector('.dot');
+        this.inputEl = container.querySelector('textarea');
+        this.sendBtn = container.querySelector('.send');
+
+        this.launcherEl?.addEventListener('click', () => this.openChat());
+        container.querySelector('.close')?.addEventListener('click', () => this.closeChat());
+        this.sendBtn?.addEventListener('click', () => this.submit());
+        this.inputEl?.addEventListener('input', () => this.autosize());
+        this.inputEl?.addEventListener('keydown', (ev) => {
+            if (ev.key === 'Enter' && !ev.shiftKey) {
+                ev.preventDefault();
+                this.submit();
+            }
+        });
+
+        const pcForm = container.querySelector('.pc-form');
+        pcForm?.addEventListener('submit', (ev) => {
+            ev.preventDefault();
+            this.handlePrechatSubmit(pcForm as HTMLFormElement);
+        });
+
+        // Full-page mode connects eagerly (there's no launcher click to trigger it) —
+        // but only once any identity gate is cleared.
+        if (fullpage && !gating) void this.controller?.connect().catch(() => {});
+
+        this.syncOpenState();
+        if (!gating) this.renderMessages(resolved.greeting);
+        this.renderStatus();
+        this.renderComposerState();
+    }
+
+    /** Collect identity from the pre-chat form, then drop into the chat view. */
+    private handlePrechatSubmit(form: HTMLFormElement): void {
+        if (!form.reportValidity()) return;
+        const data = new FormData(form);
+        const val = (k: string) => ((data.get(k) as string | null)?.trim() || undefined);
+        this.controller?.setUserInfo({ name: val('name'), email: val('email'), phone: val('phone') });
+        this.userInfoSatisfied = true;
+        this.render();
+        void this.controller?.connect().catch(() => {});
+    }
+
+    /** Send a starter prompt (from a chip click). */
+    private submitPrompt(text: string): void {
+        if (!this.inputEl) return;
+        this.inputEl.value = text;
+        this.submit();
+    }
+
+    private syncOpenState(): void {
+        // In full-page mode the panel always fills the host; nothing to toggle.
+        if (this.panelEl?.classList.contains('fullpage')) {
+            this.inputEl?.focus();
+            return;
+        }
+        this.panelEl?.classList.toggle('hidden', !this.open);
+        this.launcherEl?.classList.toggle('hidden', this.open);
+        if (this.open) this.inputEl?.focus();
+    }
+
+    /** Grow the textarea with its content, up to the CSS max-height. */
+    private autosize(): void {
+        const ta = this.inputEl;
+        if (!ta) return;
+        ta.style.height = 'auto';
+        ta.style.height = `${ta.scrollHeight}px`;
+    }
+
+    private renderMessages(greeting: string): void {
+        if (!this.messagesEl) return;
+        this.messagesEl.replaceChildren();
+
+        if (this.messages.length === 0 && greeting) {
+            this.messagesEl.appendChild(this.buildRow('assistant', this.greetingBubble(greeting)));
+        }
+
+        // Starter-prompt chips: shown until the visitor sends their first message.
+        if (!this.hasSent && this.messages.length === 0 && this.examplePrompts.length > 0) {
+            const chips = document.createElement('div');
+            chips.className = 'prompts';
+            for (const prompt of this.examplePrompts) {
+                const chip = document.createElement('button');
+                chip.type = 'button';
+                chip.className = 'chip';
+                chip.textContent = prompt;
+                chip.addEventListener('click', () => this.submitPrompt(prompt));
+                chips.appendChild(chip);
+            }
+            this.messagesEl.appendChild(chips);
+        }
+
+        for (const msg of this.messages) {
+            const bubble = document.createElement('div');
+            bubble.className = `bubble ${msg.role}`;
+            if (msg.role === 'assistant' && msg.streaming && !msg.text) {
+                // No text yet → animated typing indicator.
+                bubble.classList.add('typing');
+                bubble.append(this.typingDot(), this.typingDot(), this.typingDot());
+            } else if (msg.streaming) {
+                bubble.classList.add('cursor');
+                bubble.textContent = msg.text;
+            } else {
+                bubble.textContent = msg.text;
+            }
+            this.messagesEl.appendChild(this.buildRow(msg.role, bubble));
+
+            // Render a "Sources (N)" section under any assistant message whose
+            // terminal eventual_response carried citations.
+            if (msg.role === 'assistant' && !msg.streaming && msg.citations && msg.citations.length > 0) {
+                this.messagesEl.appendChild(this.renderSources(msg.citations));
+            }
+        }
+        this.messagesEl.scrollTop = this.messagesEl.scrollHeight;
+    }
+
+    /** Wrap a bubble in a `.row`, prefixing assistant rows with a mini avatar. */
+    private buildRow(role: 'user' | 'assistant', bubble: HTMLElement): HTMLElement {
+        const row = document.createElement('div');
+        row.className = `row ${role}`;
+        if (role === 'assistant') {
+            const mini = document.createElement('div');
+            mini.className = 'mini';
+            mini.innerHTML = ICON.bot; // static, trusted
+            row.appendChild(mini);
+        }
+        row.appendChild(bubble);
+        return row;
+    }
+
+    private greetingBubble(greeting: string): HTMLElement {
+        const b = document.createElement('div');
+        b.className = 'bubble assistant greeting';
+        b.textContent = greeting;
+        return b;
+    }
+
+    private typingDot(): HTMLElement {
+        return document.createElement('i');
+    }
+
+    /**
+     * Build the collapsible "Sources (N)" block for an assistant message's
+     * citations. Title/snippet are set via `textContent` (never innerHTML) so
+     * citation text can't inject markup; only the static chevron + numeric count
+     * use innerHTML.
+     */
+    private renderSources(citations: Citation[]): HTMLElement {
+        const wrap = document.createElement('div');
+        wrap.className = 'sources';
+        wrap.setAttribute('part', 'sources');
+
+        const details = document.createElement('details');
+        details.open = true;
+
+        const summary = document.createElement('summary');
+        const chev = document.createElement('span');
+        chev.className = 'chev';
+        chev.innerHTML = ICON.chev; // static, trusted
+        const label = document.createElement('span');
+        label.textContent = 'Sources';
+        const count = document.createElement('span');
+        count.className = 'count';
+        count.textContent = String(citations.length);
+        summary.append(chev, label, count);
+        details.appendChild(summary);
+
+        const list = document.createElement('ol');
+        for (const c of citations) {
+            const li = document.createElement('li');
+
+            let titleEl: HTMLElement;
+            // SECURITY: only absolute http(s) URLs may become a link href. A
+            // citation URL comes from indexed content (web/GitHub connectors), so
+            // an attacker-influenceable doc could carry `javascript:`/`data:`/
+            // `vbscript:` — assigning those to `a.href` is a one-click XSS. Anything
+            // that isn't a valid absolute http(s) URL renders as plain text.
+            const safeUrl = safeHttpUrl(c.url);
+            if (safeUrl) {
+                const a = document.createElement('a');
+                a.className = 'src-title';
+                a.href = safeUrl;
+                a.target = '_blank';
+                a.rel = 'noopener noreferrer';
+                titleEl = a;
+            } else {
+                titleEl = document.createElement('span');
+                titleEl.className = 'src-title';
+            }
+            titleEl.textContent = c.title || c.id || 'Source';
+            li.appendChild(titleEl);
+
+            if (c.snippet) {
+                const snip = document.createElement('span');
+                snip.className = 'src-snippet';
+                snip.textContent = c.snippet;
+                li.appendChild(snip);
+            }
+            list.appendChild(li);
+        }
+        details.appendChild(list);
+        wrap.appendChild(details);
+        return wrap;
+    }
+
+    private renderStatus(): void {
+        const label: Record<ConnectionStatus, string> = {
+            idle: '',
+            connecting: 'Connecting…',
+            ready: 'Online',
+            error: 'Connection issue',
+            closed: 'Disconnected',
+        };
+        if (this.statusEl) this.statusEl.textContent = label[this.status];
+        if (this.dotEl) {
+            // ready → green (no modifier); connecting → amber; error → red; else grey.
+            const mod = this.status === 'ready' ? '' : this.status === 'connecting' ? ' connecting' : this.status === 'error' ? ' error' : ' off';
+            this.dotEl.className = `dot${mod}`;
+        }
+    }
+
+    private renderComposerState(): void {
+        const busy = this.status === 'connecting';
+        if (this.sendBtn) this.sendBtn.disabled = busy;
+        if (this.inputEl) this.inputEl.disabled = busy;
+    }
+
+    private submit(): void {
+        if (!this.inputEl || !this.controller) return;
+        const text = this.inputEl.value;
+        if (!text.trim()) return;
+        this.inputEl.value = '';
+        this.hasSent = true;
+        this.autosize();
+        void this.controller.send(text);
+    }
+}
+
+function escapeHtml(value: string): string {
+    return value.replace(/[&<>"']/g, (c) => {
+        switch (c) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            default:
+                return '&#39;';
+        }
+    });
+}
+
+/** Register the custom element once. Safe to call multiple times. */
+export function defineChatWidget(): void {
+    if (typeof customElements !== 'undefined' && !customElements.get(ELEMENT_TAG)) {
+        customElements.define(ELEMENT_TAG, SmoothAgentChatElement);
+    }
+}
+
+/**
+ * Programmatically create, configure, and append a widget to the page.
+ * Returns the element so the host can drive `openChat()` / `closeChat()`.
+ */
+export function mountChatWidget(config: ChatWidgetConfig, target: HTMLElement = document.body): SmoothAgentChatElement {
+    defineChatWidget();
+    const el = document.createElement(ELEMENT_TAG) as SmoothAgentChatElement;
+    el.configure(config);
+    target.appendChild(el);
+    return el;
+}
+
+/**
+ * Ergonomic helper for the full-page layout: mounts a `<smooth-agent-chat>` in
+ * `mode: "fullpage"` (no launcher — the chat fills its container/viewport with a
+ * Smooth-branded header, a scrollable message list, and an input bar) and
+ * returns the element.
+ *
+ * `target` defaults to `document.body`; pass a sized container to embed the
+ * full-page chat inside a layout region (e.g. a `/chat` route shell or an
+ * iframe). The `mode` is forced to `"fullpage"` regardless of the passed config.
+ *
+ * ```ts
+ * mountFullPageChat({ endpoint: 'wss://…/ws', agentId: '…', agentName: 'Support' });
+ * ```
+ */
+export function mountFullPageChat(config: Omit<ChatWidgetConfig, 'mode'>, target: HTMLElement = document.body): SmoothAgentChatElement {
+    return mountChatWidget({ ...config, mode: 'fullpage' }, target);
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @smooai/chat-widget — an embeddable chat widget for the smooth-operator
+ * protocol. Framework-light web component that speaks the schema-driven WebSocket
+ * protocol via `@smooai/smooth-operator`.
+ *
+ * ESM library entry. For bundler-based hosts:
+ *
+ * ```ts
+ * import { defineChatWidget, mountChatWidget } from '@smooai/chat-widget';
+ *
+ * // Declarative: register the element, then drop <smooth-agent-chat …> in markup.
+ * defineChatWidget();
+ *
+ * // Or programmatic:
+ * const widget = mountChatWidget({ endpoint: 'wss://…/ws', agentId: '…' });
+ * widget.openChat();
+ * ```
+ *
+ * For a plain `<script>` embed, use the standalone IIFE bundle
+ * (`dist/chat-widget.global.js`), which auto-registers the element on load.
+ */
+export {
+    SmoothAgentChatElement,
+    ELEMENT_TAG,
+    defineChatWidget,
+    mountChatWidget,
+    mountFullPageChat,
+} from './element.js';
+export type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
+export {
+    ConversationController,
+    type ChatMessage,
+    type Citation,
+    type ConnectionStatus,
+    type ConversationEvents,
+    type Role,
+} from './conversation.js';

package/src/logo.ts

@@ -0,0 +1,9 @@
+/**
+ * The Smooth logo, inlined as an SVG string so the full-page header can render
+ * it without a separate network fetch (the IIFE bundle is self-contained).
+ *
+ * GENERATED from `assets/smooth-logo.svg` — do not edit by hand. Regenerate with:
+ *   node -e ...  (see the commit that added this file)
+ */
+/* eslint-disable */
+export const SMOOTH_LOGO_SVG = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<svg id=\"Layer_1\" data-name=\"Layer 1\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" viewBox=\"0 0 550 135\">\n  <defs>\n    <style>\n      .cls-1 {\n        fill: url(#linear-gradient-3);\n      }\n\n      .cls-2 {\n        fill: url(#linear-gradient-2);\n      }\n\n      .cls-3 {\n        fill: url(#linear-gradient);\n        fill-rule: evenodd;\n      }\n    </style>\n    <linearGradient id=\"linear-gradient\" x1=\"115.59\" y1=\"112.81\" x2=\"25.08\" y2=\"22.3\" gradientUnits=\"userSpaceOnUse\">\n      <stop offset=\".3\" stop-color=\"#f49f0a\"/>\n      <stop offset=\".79\" stop-color=\"#fb7a4d\"/>\n      <stop offset=\"1\" stop-color=\"#ff6b6c\"/>\n    </linearGradient>\n    <linearGradient id=\"linear-gradient-2\" x1=\"360.91\" y1=\"152.01\" x2=\"202.32\" y2=\"-6.59\" xlink:href=\"#linear-gradient\"/>\n    <linearGradient id=\"linear-gradient-3\" x1=\"443.91\" y1=\"30.15\" x2=\"531.36\" y2=\"117.59\" gradientUnits=\"userSpaceOnUse\">\n      <stop offset=\".43\" stop-color=\"#00a6a6\"/>\n      <stop offset=\"1\" stop-color=\"#1238dd\"/>\n    </linearGradient>\n  </defs>\n  <path class=\"cls-3\" d=\"M48.28,14.96c-12.39,5.21-22.54,14.64-28.65,26.61-6.12,11.97-7.8,25.72-4.77,38.81,3.04,13.09,10.6,24.69,21.36,32.75,10.76,8.06,24.02,12.05,37.44,11.28,13.42-.77,26.13-6.26,35.9-15.5,9.76-9.24,15.95-21.63,17.46-34.99,1.51-13.36-1.74-26.82-9.19-38.01-1.07-1.61-.64-3.78.97-4.85,1.61-1.07,3.78-.64,4.85.97,8.36,12.56,12.02,27.68,10.32,42.67-1.7,15-8.64,28.91-19.61,39.28-10.96,10.37-25.24,16.54-40.31,17.4-15.07.87-29.96-3.62-42.04-12.66-12.08-9.05-20.58-22.07-23.99-36.77-3.41-14.7-1.51-30.14,5.35-43.58,6.87-13.44,18.26-24.02,32.17-29.87,13.91-5.85,29.44-6.6,43.85-2.11,1.85.57,2.88,2.54,2.3,4.38-.57,1.85-2.54,2.88-4.38,2.3-12.83-4-26.67-3.33-39.06,1.88ZM111.39,19.75c0,2.07-1.68,3.75-3.75,3.75s-3.75-1.68-3.75-3.75,1.68-3.75,3.75-3.75,3.75,1.68,3.75,3.75ZM64.64,59.93c0,1.91,2.39,2.56,7.69,3.88,3.89.97,6.6,2.18,8.15,3.63,1.53,1.45,2.29,3.53,2.29,6.25,0,3.57-1.03,6.26-3.11,8.08-2.07,1.82-5.09,2.73-9.09,2.73h-9.6c-1.97,0-3.57-1.6-3.59-3.57-.01-1.99,1.6-3.61,3.59-3.61h9.41c3.15-.12,4.79-.95,4.91-2.47,0-1.3-1.03-2.21-3.07-2.73-6.91-1.72-11.11-3.44-12.6-5.15-1.48-1.71-2.23-3.77-2.23-6.19,0-6.59,3.2-9.85,9.59-9.8h10.77c1.99,0,3.6,1.61,3.6,3.59s-1.61,3.59-3.6,3.59h-9.69c-1.83,0-3.43.06-3.43,1.77Z\"/>\n  <path class=\"cls-2\" d=\"M205.52,48.44h-8.86c-.44-3.75-2.23-6.65-5.38-8.72-3.16-2.07-7.03-3.1-11.6-3.1h0c-3.35,0-6.27.54-8.78,1.62-2.49,1.09-4.44,2.59-5.84,4.48-1.39,1.89-2.08,4.05-2.08,6.46h0c0,2.01.49,3.75,1.46,5.2.97,1.44,2.22,2.63,3.74,3.58,1.53.95,3.13,1.72,4.8,2.32,1.68.6,3.22,1.09,4.62,1.46h0l7.68,2.06c1.97.52,4.17,1.23,6.6,2.14,2.43.92,4.75,2.16,6.98,3.72,2.23,1.56,4.07,3.56,5.52,6,1.45,2.44,2.18,5.43,2.18,8.98h0c0,4.08-1.07,7.77-3.2,11.08-2.12,3.29-5.22,5.91-9.3,7.86-4.08,1.95-9.02,2.92-14.82,2.92h0c-5.43,0-10.11-.87-14.06-2.62-3.95-1.75-7.05-4.19-9.3-7.32-2.25-3.12-3.53-6.75-3.84-10.88h9.46c.25,2.85,1.22,5.21,2.9,7.06,1.69,1.87,3.83,3.25,6.42,4.14,2.6.89,5.41,1.34,8.42,1.34h0c3.49,0,6.63-.57,9.4-1.72,2.79-1.13,4.99-2.73,6.62-4.8,1.63-2.05,2.44-4.46,2.44-7.22h0c0-2.51-.7-4.55-2.1-6.12-1.41-1.57-3.26-2.85-5.54-3.84-2.29-.99-4.77-1.85-7.44-2.58h0l-9.3-2.66c-5.91-1.71-10.59-4.13-14.04-7.28-3.44-3.16-5.16-7.29-5.16-12.38h0c0-4.23,1.15-7.93,3.46-11.1,2.29-3.16,5.39-5.62,9.3-7.38,3.91-1.76,8.27-2.64,13.08-2.64h0c4.88,0,9.21.87,13,2.6,3.8,1.73,6.81,4.11,9.04,7.12,2.23,3,3.4,6.41,3.52,10.22h0ZM229.16,105.18h-8.72v-56.74h8.42v8.86h.74c1.19-3.03,3.1-5.38,5.74-7.06,2.63-1.69,5.79-2.54,9.48-2.54h0c3.75,0,6.87.85,9.36,2.54,2.51,1.68,4.46,4.03,5.86,7.06h.58c1.45-2.92,3.63-5.25,6.54-7,2.91-1.73,6.39-2.6,10.46-2.6h0c5.07,0,9.21,1.58,12.44,4.74,3.23,3.17,4.84,8.09,4.84,14.76h0v37.98h-8.72v-37.98c0-4.19-1.14-7.18-3.42-8.98-2.29-1.79-4.99-2.68-8.1-2.68h0c-3.99,0-7.07,1.2-9.26,3.6-2.2,2.4-3.3,5.43-3.3,9.1h0v36.94h-8.86v-38.86c0-3.23-1.05-5.83-3.14-7.82-2.09-1.97-4.79-2.96-8.08-2.96h0c-2.27,0-4.38.6-6.34,1.8-1.96,1.21-3.53,2.88-4.72,5-1.2,2.13-1.8,4.59-1.8,7.38h0v35.46ZM333.9,106.36h0c-5.12,0-9.61-1.22-13.46-3.66-3.85-2.44-6.86-5.85-9.02-10.24-2.15-4.37-3.22-9.49-3.22-15.36h0c0-5.91,1.07-11.07,3.22-15.48,2.16-4.4,5.17-7.82,9.02-10.26,3.85-2.44,8.34-3.66,13.46-3.66h0c5.12,0,9.61,1.22,13.46,3.66,3.85,2.44,6.86,5.86,9.02,10.26,2.15,4.41,3.22,9.57,3.22,15.48h0c0,5.87-1.07,10.99-3.22,15.36-2.16,4.39-5.17,7.8-9.02,10.24-3.85,2.44-8.34,3.66-13.46,3.66ZM333.9,98.52h0c3.89,0,7.09-.99,9.6-2.98,2.52-2,4.38-4.63,5.58-7.88,1.21-3.25,1.82-6.77,1.82-10.56h0c0-3.79-.61-7.32-1.82-10.6-1.2-3.27-3.06-5.91-5.58-7.94-2.51-2.01-5.71-3.02-9.6-3.02h0c-3.89,0-7.09,1.01-9.6,3.02-2.51,2.03-4.37,4.67-5.58,7.94-1.2,3.28-1.8,6.81-1.8,10.6h0c0,3.79.6,7.31,1.8,10.56,1.21,3.25,3.07,5.88,5.58,7.88,2.51,1.99,5.71,2.98,9.6,2.98ZM395.94,106.36h0c-5.12,0-9.61-1.22-13.46-3.66-3.85-2.44-6.85-5.85-9-10.24-2.16-4.37-3.24-9.49-3.24-15.36h0c0-5.91,1.08-11.07,3.24-15.48,2.15-4.4,5.15-7.82,9-10.26,3.85-2.44,8.34-3.66,13.46-3.66h0c5.12,0,9.61,1.22,13.46,3.66,3.85,2.44,6.86,5.86,9.02,10.26,2.16,4.41,3.24,9.57,3.24,15.48h0c0,5.87-1.08,10.99-3.24,15.36-2.16,4.39-5.17,7.8-9.02,10.24-3.85,2.44-8.34,3.66-13.46,3.66ZM395.94,98.52h0c3.89,0,7.09-.99,9.6-2.98,2.52-2,4.38-4.63,5.58-7.88,1.21-3.25,1.82-6.77,1.82-10.56h0c0-3.79-.61-7.32-1.82-10.6-1.2-3.27-3.06-5.91-5.58-7.94-2.51-2.01-5.71-3.02-9.6-3.02h0c-3.88,0-7.08,1.01-9.6,3.02-2.51,2.03-4.37,4.67-5.58,7.94-1.2,3.28-1.8,6.81-1.8,10.6h0c0,3.79.6,7.31,1.8,10.56,1.21,3.25,3.07,5.88,5.58,7.88,2.52,1.99,5.72,2.98,9.6,2.98Z\"/>\n  <path class=\"cls-1\" d=\"M467.88,48.02v13.28h-35.79v-13.28h35.79ZM439.68,34.38h17.89v53.42c0,1.5.36,2.62,1.08,3.36.72.74,1.88,1.1,3.49,1.1.62,0,1.48-.07,2.59-.21,1.11-.14,1.91-.27,2.38-.41l2.31,13.02c-2.02.58-3.97.97-5.84,1.18-1.88.21-3.66.31-5.33.31-6.08,0-10.7-1.43-13.84-4.28-3.15-2.85-4.72-7.01-4.72-12.48v-55.01ZM506.59,72.63v32.71h-17.89V28.95h17.53v33.53h-1.13c1.4-4.55,3.6-8.21,6.59-11,2.99-2.79,7.01-4.18,12.07-4.18,4,0,7.48.89,10.46,2.67,2.97,1.78,5.28,4.29,6.92,7.54,1.64,3.25,2.46,7.02,2.46,11.33v36.5h-17.89v-33.02c0-3.21-.82-5.73-2.46-7.56-1.64-1.83-3.93-2.74-6.87-2.74-1.92,0-3.62.42-5.1,1.26-1.49.84-2.64,2.04-3.46,3.61-.82,1.57-1.23,3.49-1.23,5.74Z\"/>\n</svg>";

package/src/standalone.ts

@@ -0,0 +1,33 @@
+/**
+ * Standalone IIFE entry. Bundled (with the protocol client inlined) into
+ * `dist/chat-widget.global.js` for a plain `<script src="…">` embed.
+ *
+ * On load it:
+ *   - registers the `<smooth-agent-chat>` custom element, and
+ *   - exposes the programmatic API on the IIFE global `SmoothAgentChat`
+ *     (`window.SmoothAgentChat.mount({ endpoint, agentId })`).
+ *
+ * A host page can then either drop the element in markup:
+ *   <smooth-agent-chat endpoint="wss://…/ws" agent-id="…"></smooth-agent-chat>
+ * or mount it programmatically:
+ *   SmoothAgentChat.mount({ endpoint: 'wss://…/ws', agentId: '…' });
+ */
+import type { ChatWidgetConfig } from './config.js';
+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: ChatWidgetConfig, target?: HTMLElement): SmoothAgentChatElement {
+    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: Omit<ChatWidgetConfig, 'mode'>, target?: HTMLElement): SmoothAgentChatElement {
+    return mountFullPageChat(config, target);
+}