@smooai/chat-widget 0.5.2 → 0.7.0

package/src/element.ts

@@ -16,8 +16,9 @@
  */
 import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
 import { needsUserInfo, resolveConfig } from './config.js';
-import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type Interrupt } from './conversation.js';
+import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt } from './conversation.js';
 import { SMOOTH_LOGO_SVG } from './logo.js';
+import { cleanCitationSnippet, escapeHtml, renderMarkdown, safeHttpUrl } from './markdown.js';
 import { buildStyles } from './styles.js';
 
 export const ELEMENT_TAG = 'smooth-agent-chat';
@@ -45,24 +46,9 @@ const ICON = {
     shield: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 3 5 6v5c0 4.4 3 7.2 7 8.5 4-1.3 7-4.1 7-8.5V6l-7-3Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="m9 11.5 2 2 4-4" stroke="currentColor" stroke-width="1.7" 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;
-    }
-}
+// `safeHttpUrl` / `escapeHtml` live in `./markdown.js` (the markdown renderer
+// needs them too); re-exported here for back-compat with existing importers.
+export { escapeHtml, safeHttpUrl } from './markdown.js';
 
 export class SmoothAgentChatElement extends HTMLElement {
     static get observedAttributes(): readonly string[] {
@@ -82,9 +68,17 @@ export class SmoothAgentChatElement extends HTMLElement {
     private hasSent = false;
     /** Starter prompts shown as chips in the empty state. */
     private examplePrompts: string[] = [];
+    /** Resolved greeting text, cached so async (rAF) renders can reuse it. */
+    private greeting = '';
     /** Current mid-turn interrupt (OTP / tool-confirmation), or null. */
     private interrupt: Interrupt | null = null;
     private interruptEl: HTMLElement | null = null;
+    /** Cross-device "restore my chats" flow state (ADR-048 §c). */
+    private identityRestore: IdentityRestore = { phase: 'idle' };
+    /** Whether the cross-device restore affordance is offered (config). */
+    private allowChatRestore = true;
+    /** True while the pre-chat identity gate is showing (blocks premature connect). */
+    private gating = false;
 
     // Cached DOM refs (populated in render()).
     private panelEl: HTMLElement | null = null;
@@ -95,6 +89,22 @@ export class SmoothAgentChatElement extends HTMLElement {
     private inputEl: HTMLTextAreaElement | null = null;
     private sendBtn: HTMLButtonElement | null = null;
 
+    // ── Smooth streaming reveal ──
+    // Tokens arrive in variable-size bursts at uneven rates, so revealing text in
+    // lockstep with arrival looks jerky. Instead we buffer the full target text
+    // and reveal it via a requestAnimationFrame "typewriter" at an adaptive rate
+    // (chars/frame scales with the pending backlog so it never falls behind the
+    // network). State below tracks the single in-flight streaming bubble.
+    /** The live streaming assistant bubble whose textContent the rAF loop drives. */
+    private streamBubbleEl: HTMLElement | null = null;
+    /** Message id the reveal is bound to (guards against stale frames after rebuilds). */
+    private streamMsgId: string | null = null;
+    /** Full buffered target text for the streaming message (grows as tokens arrive). */
+    private streamTarget = '';
+    /** How many chars of {@link streamTarget} are currently shown. */
+    private displayedLength = 0;
+    private rafId = 0;
+
     constructor() {
         super();
         this.root = this.attachShadow({ mode: 'open' });
@@ -107,6 +117,7 @@ export class SmoothAgentChatElement extends HTMLElement {
 
     disconnectedCallback(): void {
         this.mounted = false;
+        this.resetReveal();
         this.controller?.disconnect();
         this.controller = null;
     }
@@ -131,7 +142,10 @@ export class SmoothAgentChatElement extends HTMLElement {
     openChat(): void {
         this.open = true;
         this.syncOpenState();
-        void this.controller?.connect().catch(() => {});
+        // Don't connect while the pre-chat identity gate is unsatisfied — connecting
+        // here would create a session BEFORE the visitor submits their name/email/
+        // consent, sending an empty identity. The form's submit handler connects.
+        if (!this.gating) void this.controller?.connect().catch(() => {});
     }
 
     /** Collapse the chat panel back to the launcher. */
@@ -158,6 +172,7 @@ export class SmoothAgentChatElement extends HTMLElement {
             userName: this.overrides.userName,
             userEmail: this.overrides.userEmail,
             userPhone: this.overrides.userPhone,
+            authContext: this.overrides.authContext,
             placeholder: this.overrides.placeholder ?? this.getAttribute('placeholder') ?? undefined,
             greeting: this.overrides.greeting ?? this.getAttribute('greeting') ?? undefined,
             connectionErrorMessage: this.overrides.connectionErrorMessage,
@@ -166,6 +181,9 @@ export class SmoothAgentChatElement extends HTMLElement {
             requireName: this.overrides.requireName,
             requireEmail: this.overrides.requireEmail,
             requirePhone: this.overrides.requirePhone,
+            collectPhone: this.overrides.collectPhone,
+            collectConsent: this.overrides.collectConsent,
+            allowChatRestore: this.overrides.allowChatRestore,
             allowAnonymous: this.overrides.allowAnonymous,
             theme,
         };
@@ -181,13 +199,14 @@ export class SmoothAgentChatElement extends HTMLElement {
         }
         const resolved = resolveConfig(config);
 
+        this.allowChatRestore = resolved.allowChatRestore;
+
         // (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);
+                    this.handleMessages(messages, resolved.greeting);
                 },
                 onStatus: (status) => {
                     this.status = status;
@@ -198,8 +217,17 @@ export class SmoothAgentChatElement extends HTMLElement {
                     this.interrupt = interrupt;
                     this.renderInterrupt();
                 },
+                onIdentityRestore: (state) => {
+                    this.identityRestore = state;
+                    this.renderInterrupt();
+                },
             });
             if (resolved.startOpen) this.open = true;
+            // Returning visitor: a persisted session or identity lets us skip the
+            // pre-chat gate and resume straight into the conversation (ADR-048 §b).
+            if (this.controller.hasPersistedSession() || this.controller.hasPersistedIdentity()) {
+                this.userInfoSatisfied = true;
+            }
         }
 
         const fullpage = resolved.mode === 'fullpage';
@@ -232,13 +260,26 @@ export class SmoothAgentChatElement extends HTMLElement {
                     <button class="close" aria-label="Close chat">${ICON.close}</button>
                 </div>`;
 
-        // Remember starter prompts for the empty-state chips.
+        // Remember starter prompts + greeting for the empty-state chips / async renders.
         this.examplePrompts = resolved.examplePrompts;
+        this.greeting = resolved.greeting;
 
         // 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>`;
+        this.gating = gating;
+        // Phone is collected by default (optional unless requirePhone). Consent
+        // checkboxes default to shown, explicit + unchecked (ADR-048 §a/§3).
+        const showPhone = resolved.requirePhone || resolved.collectPhone;
+        const field = (name: string, type: string, label: string, autocomplete: string, required: boolean) =>
+            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}"${required ? ' required' : ''} /></label>`;
+        const consentBox = (name: string, label: string) =>
+            `<label class="pc-consent"><input name="${name}" type="checkbox" /><span>${escapeHtml(label)}</span></label>`;
+        const consentHtml = resolved.collectConsent
+            ? `<div class="pc-consents">
+                    ${consentBox('emailOptIn', 'Email me product news and offers.')}
+                    ${consentBox('smsOptIn', 'Text me updates by SMS. Message/data rates may apply.')}
+                </div>`
+            : '';
         const prechatHtml = `
             <div class="prechat">
                 <div class="pc-head">
@@ -246,12 +287,14 @@ export class SmoothAgentChatElement extends HTMLElement {
                     <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') : ''}
+                    ${resolved.requireName ? field('name', 'text', 'Name', 'name', true) : ''}
+                    ${resolved.requireEmail ? field('email', 'email', 'Email', 'email', true) : ''}
+                    ${showPhone ? field('phone', 'tel', 'Phone', 'tel', resolved.requirePhone) : ''}
+                    ${consentHtml}
                     <button type="submit" class="pc-submit">Start chat</button>
                 </form>
             </div>`;
+        const restoreLink = this.allowChatRestore ? ` · <button type="button" class="restore-link">Restore my chats</button>` : '';
         const chatHtml = `
                 <div class="messages"></div>
                 <div class="interrupt hidden"></div>
@@ -260,7 +303,7 @@ export class SmoothAgentChatElement extends HTMLElement {
                         <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 class="footer">powered by <b>smooth&#8209;operator</b>${restoreLink}</div>
                 </div>`;
 
         const container = document.createElement('div');
@@ -277,6 +320,9 @@ export class SmoothAgentChatElement extends HTMLElement {
         const logoSvg = container.querySelector('.logo-wrap svg');
         if (logoSvg) logoSvg.setAttribute('class', 'logo');
 
+        // A full DOM rebuild invalidates any cached streaming-bubble ref; cancel
+        // the in-flight reveal loop so renderMessages can re-bind cleanly.
+        this.resetReveal();
         this.root.replaceChildren(style, container);
 
         this.launcherEl = container.querySelector('.launcher');
@@ -305,12 +351,27 @@ export class SmoothAgentChatElement extends HTMLElement {
             this.handlePrechatSubmit(pcForm as HTMLFormElement);
         });
 
+        // Cross-device "Restore my chats": open the panel + start the email entry.
+        // AWAIT connect() before showing the email step so a `sessionId` exists by
+        // the time the visitor submits — otherwise request-otp could go out with no
+        // session and verify-otp would then hard-error "No active session." The
+        // request-otp/verify-otp paths in the controller also require a session, so
+        // gating here keeps the affordance race-free.
+        container.querySelector('.restore-link')?.addEventListener('click', () => {
+            void (async () => {
+                this.identityRestore = { phase: 'awaiting_email' };
+                this.renderInterrupt();
+                // Establish a live session before the email entry can fire request-otp.
+                await this.controller?.connect().catch(() => {});
+            })();
+        });
+
         // 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);
+        if (!gating) this.renderMessages();
         this.renderStatus();
         this.renderComposerState();
         this.renderInterrupt();
@@ -327,6 +388,13 @@ export class SmoothAgentChatElement extends HTMLElement {
         el.replaceChildren();
         const it = this.interrupt;
         if (!it) {
+            // No mid-turn interrupt — but the cross-device restore flow may be
+            // active, which reuses this same overlay slot.
+            if (this.identityRestore.phase !== 'idle') {
+                el.classList.remove('hidden');
+                el.appendChild(this.buildRestoreCard());
+                return;
+            }
             el.classList.add('hidden');
             return;
         }
@@ -412,12 +480,189 @@ export class SmoothAgentChatElement extends HTMLElement {
         el.appendChild(card);
     }
 
-    /** Collect identity from the pre-chat form, then drop into the chat view. */
+    /**
+     * Build the cross-device "Restore my chats" card (ADR-048 §c). Reuses the
+     * same overlay slot + visual language as the OTP interrupt. All server-supplied
+     * strings (masked destination, conversation previews) are set via `textContent`
+     * — never innerHTML — so they can't inject markup; only the static lock icon
+     * uses innerHTML.
+     */
+    private buildRestoreCard(): HTMLElement {
+        const state = this.identityRestore;
+        const card = document.createElement('div');
+        card.className = 'int-card';
+
+        const head = document.createElement('div');
+        head.className = 'int-head';
+        const ico = document.createElement('span');
+        ico.className = 'int-ico';
+        ico.innerHTML = ICON.lock; // static, trusted
+        const title = document.createElement('span');
+        title.className = 'int-title';
+        title.textContent = 'Restore your chats';
+        head.append(ico, title);
+        card.appendChild(head);
+
+        const close = document.createElement('button');
+        close.className = 'int-close';
+        close.type = 'button';
+        close.setAttribute('aria-label', 'Cancel');
+        close.textContent = '×';
+        close.addEventListener('click', () => {
+            this.controller?.cancelIdentityRestore();
+            this.identityRestore = { phase: 'idle' };
+            this.renderInterrupt();
+        });
+        card.appendChild(close);
+
+        if (state.phase === 'awaiting_email') {
+            const desc = document.createElement('div');
+            desc.className = 'int-desc';
+            desc.textContent = "Enter your email and we'll send a code to find your previous chats.";
+            card.appendChild(desc);
+
+            const row = document.createElement('div');
+            row.className = 'int-row';
+            const input = document.createElement('input');
+            input.className = 'int-input';
+            input.type = 'email';
+            input.autocomplete = 'email';
+            input.placeholder = 'you@example.com';
+            const go = () => {
+                const email = input.value.trim();
+                if (email) void this.controller?.requestIdentityOtp(email, 'email');
+            };
+            input.addEventListener('keydown', (ev) => {
+                if (ev.key === 'Enter') {
+                    ev.preventDefault();
+                    go();
+                }
+            });
+            const send = document.createElement('button');
+            send.className = 'int-btn primary';
+            send.type = 'button';
+            send.textContent = 'Send code';
+            send.addEventListener('click', go);
+            row.append(input, send);
+            card.appendChild(row);
+            if (state.error) {
+                const err = document.createElement('div');
+                err.className = 'int-error';
+                err.textContent = state.error;
+                card.appendChild(err);
+            }
+            queueMicrotask(() => input.focus());
+        } else if (state.phase === 'requesting' || state.phase === 'verifying' || state.phase === 'resolving') {
+            const msg = document.createElement('div');
+            msg.className = 'int-sent';
+            msg.textContent = state.phase === 'requesting' ? 'Sending a code…' : state.phase === 'verifying' ? 'Verifying…' : 'Finding your chats…';
+            card.appendChild(msg);
+        } else if (state.phase === 'awaiting_code') {
+            if (state.maskedDestination) {
+                const sent = document.createElement('div');
+                sent.className = 'int-sent';
+                sent.textContent = `Code sent to ${state.maskedDestination}.`;
+                card.appendChild(sent);
+            }
+            const row = document.createElement('div');
+            row.className = 'int-row';
+            const input = document.createElement('input');
+            input.className = 'int-input';
+            input.type = 'text';
+            input.inputMode = 'numeric';
+            input.autocomplete = 'one-time-code';
+            input.placeholder = 'Enter code';
+            const submit = () => {
+                const code = input.value.trim();
+                if (code) void this.controller?.verifyIdentityOtp(code);
+            };
+            input.addEventListener('keydown', (ev) => {
+                if (ev.key === 'Enter') {
+                    ev.preventDefault();
+                    submit();
+                }
+            });
+            const verify = document.createElement('button');
+            verify.className = 'int-btn primary';
+            verify.type = 'button';
+            verify.textContent = 'Verify';
+            verify.addEventListener('click', submit);
+            row.append(input, verify);
+            card.appendChild(row);
+            if (state.error) {
+                const err = document.createElement('div');
+                err.className = 'int-error';
+                err.textContent = state.attemptsRemaining != null ? `${state.error} (${state.attemptsRemaining} left)` : state.error;
+                card.appendChild(err);
+            }
+            queueMicrotask(() => input.focus());
+        } else if (state.phase === 'resolved') {
+            if (state.conversations.length === 0) {
+                const none = document.createElement('div');
+                none.className = 'int-desc';
+                none.textContent = 'No previous chats found for that email.';
+                card.appendChild(none);
+            } else {
+                const pick = document.createElement('div');
+                pick.className = 'int-desc';
+                pick.textContent = 'Pick a conversation to continue:';
+                card.appendChild(pick);
+                const list = document.createElement('div');
+                list.className = 'restore-list';
+                for (const conv of state.conversations) {
+                    const btn = document.createElement('button');
+                    btn.type = 'button';
+                    btn.className = 'restore-item';
+                    const preview = document.createElement('span');
+                    preview.className = 'restore-preview';
+                    preview.textContent = conv.preview || 'Conversation';
+                    btn.appendChild(preview);
+                    if (conv.lastActivityAt) {
+                        const when = document.createElement('span');
+                        when.className = 'restore-when';
+                        when.textContent = this.formatWhen(conv.lastActivityAt);
+                        btn.appendChild(when);
+                    }
+                    btn.addEventListener('click', () => {
+                        void this.controller?.restoreConversation(conv.sessionId);
+                    });
+                    list.appendChild(btn);
+                }
+                card.appendChild(list);
+            }
+        } else if (state.phase === 'error') {
+            const err = document.createElement('div');
+            err.className = 'int-error';
+            err.textContent = state.message;
+            card.appendChild(err);
+        }
+
+        return card;
+    }
+
+    /** Format an ISO timestamp as a short, locale-aware label (best-effort). */
+    private formatWhen(iso: string): string {
+        const d = new Date(iso);
+        if (Number.isNaN(d.getTime())) return '';
+        try {
+            return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+        } catch {
+            return '';
+        }
+    }
+
+    /** Collect identity + consent 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') });
+        const checked = (k: string) => data.get(k) === 'on';
+        this.controller?.setUserInfo({
+            name: val('name'),
+            email: val('email'),
+            phone: val('phone'),
+            consent: { emailOptIn: checked('emailOptIn'), smsOptIn: checked('smsOptIn') },
+        });
         this.userInfoSatisfied = true;
         this.render();
         void this.controller?.connect().catch(() => {});
@@ -449,10 +694,52 @@ export class SmoothAgentChatElement extends HTMLElement {
         ta.style.height = `${ta.scrollHeight}px`;
     }
 
-    private renderMessages(greeting: string): void {
+    /**
+     * Receive a new message snapshot from the controller and update the view.
+     *
+     * `onMessages` fires on *every* `stream_token` delta. Rebuilding the whole
+     * list each frame is wasteful and fights the smooth reveal, so we take the
+     * cheap path when the only change is the trailing streaming assistant message
+     * growing: just bump the reveal *target* (the rAF loop drains it). Any
+     * structural change (new message, finalize, citations) triggers a full
+     * rebuild via {@link renderMessages}.
+     */
+    private handleMessages(messages: ChatMessage[], greeting: string): void {
+        this.greeting = greeting;
+        const prev = this.messages;
+        const last = messages[messages.length - 1];
+        const prevLast = prev[prev.length - 1];
+
+        const structural =
+            messages.length !== prev.length ||
+            !last ||
+            !prevLast ||
+            last.id !== prevLast.id ||
+            last.role !== prevLast.role ||
+            // finalize transition (streaming → done) needs the markdown render + sources
+            last.streaming !== prevLast.streaming ||
+            // first token after the typing indicator needs the bubble swapped in
+            (!!last.streaming && !prevLast.text && !!last.text);
+
+        this.messages = messages;
+
+        if (!structural && last && last.streaming && last.id === this.streamMsgId) {
+            // Fast path: the streaming tail just grew. Bump the reveal target and
+            // let the rAF loop catch up — no DOM rebuild, no per-token reflow.
+            this.streamTarget = last.text;
+            this.ensureRevealLoop();
+            return;
+        }
+
+        this.renderMessages();
+    }
+
+    private renderMessages(): void {
         if (!this.messagesEl) return;
+        this.resetReveal();
         this.messagesEl.replaceChildren();
 
+        const greeting = this.greeting;
         if (this.messages.length === 0 && greeting) {
             this.messagesEl.appendChild(this.buildRow('assistant', this.greetingBubble(greeting)));
         }
@@ -480,9 +767,21 @@ export class SmoothAgentChatElement extends HTMLElement {
                 bubble.classList.add('typing');
                 bubble.append(this.typingDot(), this.typingDot(), this.typingDot());
             } else if (msg.streaming) {
+                // Mid-stream: partial/unclosed markdown renders ugly (half-open
+                // `**`, dangling `[`), so keep plain text + the blinking cursor.
+                // The text is revealed gradually by the rAF typewriter; seed the
+                // bubble with whatever is already displayed and bind the reveal.
                 bubble.classList.add('cursor');
-                bubble.textContent = msg.text;
+                this.bindReveal(msg, bubble);
+            } else if (msg.role === 'assistant') {
+                // Final assistant turn → render the sanitized markdown subset.
+                // `renderMarkdown` escapes all text, drops images, gates links to
+                // http(s), and only emits an allowlisted set of tags, so this
+                // `innerHTML` cannot inject markup (see markdown.ts).
+                bubble.classList.add('md');
+                bubble.innerHTML = renderMarkdown(msg.text);
             } else {
+                // User bubbles stay plain text.
                 bubble.textContent = msg.text;
             }
             this.messagesEl.appendChild(this.buildRow(msg.role, bubble));
@@ -493,7 +792,115 @@ export class SmoothAgentChatElement extends HTMLElement {
                 this.messagesEl.appendChild(this.renderSources(msg.citations));
             }
         }
-        this.messagesEl.scrollTop = this.messagesEl.scrollHeight;
+        this.scrollToBottom(true);
+    }
+
+    // ─────────────────────── Smooth streaming reveal ───────────────────────────
+
+    /** True when the host/user prefers reduced motion (snap, no typewriter). */
+    private prefersReducedMotion(): boolean {
+        return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+
+    /**
+     * Bind the rAF typewriter to a freshly built streaming bubble. Preserves the
+     * already-revealed prefix across rebuilds (so a structural rebuild mid-stream
+     * doesn't restart the reveal from zero), then resumes the loop.
+     */
+    private bindReveal(msg: ChatMessage, bubble: HTMLElement): void {
+        const carryOver = msg.id === this.streamMsgId ? Math.min(this.displayedLength, msg.text.length) : 0;
+        this.streamBubbleEl = bubble;
+        this.streamMsgId = msg.id;
+        this.streamTarget = msg.text;
+        this.displayedLength = carryOver;
+
+        if (this.prefersReducedMotion()) {
+            // No animation: show everything immediately.
+            this.displayedLength = msg.text.length;
+            bubble.textContent = msg.text;
+            return;
+        }
+        bubble.textContent = msg.text.slice(0, this.displayedLength);
+        this.ensureRevealLoop();
+    }
+
+    /** Start the rAF loop if it isn't already running. */
+    private ensureRevealLoop(): void {
+        if (this.prefersReducedMotion() || typeof requestAnimationFrame !== 'function') {
+            // No animation (reduced-motion or no rAF): snap to the full buffer.
+            this.snapReveal();
+            return;
+        }
+        if (this.rafId) return; // already running
+        this.rafId = requestAnimationFrame(() => this.tickReveal());
+    }
+
+    /**
+     * One animation frame of the reveal. Advances `displayedLength` toward the
+     * buffered target at an ADAPTIVE rate — the deeper the backlog, the more
+     * chars per frame — so the reveal stays smooth yet never falls behind the
+     * network. Updates ONLY the bound bubble's textContent (no list rebuild).
+     */
+    private tickReveal(): void {
+        this.rafId = 0;
+        const bubble = this.streamBubbleEl;
+        if (!bubble) return;
+
+        const target = this.streamTarget;
+        const remaining = target.length - this.displayedLength;
+
+        if (remaining <= 0) {
+            // Caught up to everything buffered so far → idle. A later token bump
+            // (handleMessages → ensureRevealLoop) restarts the loop; the finalize
+            // structural rebuild snaps to the full markdown render.
+            return;
+        }
+
+        // Adaptive speed: ~1/8 of the backlog per frame (≈ catch up over a few
+        // frames), clamped to a readable floor so short bursts still animate and
+        // an aggressive ceiling so a deep buffer drains fast. At ~60fps this
+        // comfortably outruns the wire — the reveal is steady, never bursty.
+        const step = Math.max(2, Math.min(remaining, Math.ceil(remaining / 8)));
+        this.displayedLength = Math.min(target.length, this.displayedLength + step);
+        bubble.textContent = target.slice(0, this.displayedLength);
+        this.scrollToBottom(false);
+
+        this.rafId = requestAnimationFrame(() => this.tickReveal());
+    }
+
+    /** Snap the bound bubble to the full buffered text immediately (reduced-motion / no-rAF). */
+    private snapReveal(): void {
+        if (this.streamBubbleEl) {
+            this.displayedLength = this.streamTarget.length;
+            this.streamBubbleEl.textContent = this.streamTarget;
+        }
+    }
+
+    /** Cancel any in-flight reveal loop and clear its state (called on full rebuild). */
+    private resetReveal(): void {
+        if (this.rafId && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.rafId);
+        this.rafId = 0;
+        this.streamBubbleEl = null;
+        // streamMsgId/displayedLength are intentionally kept so bindReveal can
+        // carry the revealed prefix across a structural rebuild of the same msg;
+        // they're reset when a different message binds.
+    }
+
+    /**
+     * Auto-scroll the message list to the bottom — but don't fight a visitor who
+     * has scrolled up to read history. When `force` (a structural rebuild) we
+     * always pin to bottom; during the streaming reveal we only follow if the
+     * viewport is already near the bottom.
+     */
+    private scrollToBottom(force: boolean): void {
+        const el = this.messagesEl;
+        if (!el) return;
+        if (force) {
+            el.scrollTop = el.scrollHeight;
+            return;
+        }
+        const nearBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 80;
+        if (nearBottom) el.scrollTop = el.scrollHeight;
     }
 
     /** Wrap a bubble in a `.row`, prefixing assistant rows with a mini avatar. */
@@ -563,7 +970,7 @@ export class SmoothAgentChatElement extends HTMLElement {
                 a.className = 'src-title';
                 a.href = safeUrl;
                 a.target = '_blank';
-                a.rel = 'noopener noreferrer';
+                a.rel = 'noopener noreferrer nofollow';
                 titleEl = a;
             } else {
                 titleEl = document.createElement('span');
@@ -573,10 +980,18 @@ export class SmoothAgentChatElement extends HTMLElement {
             li.appendChild(titleEl);
 
             if (c.snippet) {
-                const snip = document.createElement('span');
-                snip.className = 'src-snippet';
-                snip.textContent = c.snippet;
-                li.appendChild(snip);
+                // The snippet is the raw scraped chunk — often led by page
+                // boilerplate (logo link, nav, whitespace). Trim it to a clean
+                // excerpt, then render the sanitized markdown subset. Both steps
+                // escape text + drop images/unsafe links (see markdown.ts), so
+                // this `innerHTML` is safe.
+                const cleaned = cleanCitationSnippet(c.snippet);
+                if (cleaned) {
+                    const snip = document.createElement('span');
+                    snip.className = 'src-snippet md';
+                    snip.innerHTML = renderMarkdown(cleaned);
+                    li.appendChild(snip);
+                }
             }
             list.appendChild(li);
         }
@@ -618,23 +1033,6 @@ export class SmoothAgentChatElement extends HTMLElement {
     }
 }
 
-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)) {