From d5d6168922165d674c1947b08907ab67110556c6 Mon Sep 17 00:00:00 2001
From: Brent Rager <brent@rager.tech>
Date: Sat, 27 Jun 2026 08:39:25 -0400
Subject: [PATCH] SMOODEV: Sanitized markdown rendering + smooth streaming
 reveal in chat-widget
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Assistant replies and citation snippets rendered as raw plain text, so
**bold**, numbered lists, and [links](url) showed literally. Render them
through a tiny safe-by-default markdown renderer (markdown.ts) that escapes
all text (raw <script>/<img onerror>/<iframe> stay inert), drops images,
allows only http(s) links (target=_blank + rel=noopener noreferrer nofollow),
emits an allowlisted tag set, and downgrades headings to bold so they fit a
chat bubble. Hand-rolled over markdown-it (~10KB gz) to keep the embeddable
global bundle small: +5.3KB gz for BOTH features combined. User bubbles and
mid-stream text stay plain (partial markdown renders ugly); only the final
assistant turn renders markdown. Citation snippets are cleaned first (strip
leading logo/nav boilerplate, collapse whitespace, truncate ~260 chars at a
word boundary).

Also smooth the streaming reveal: buffer incoming token text and reveal it via
a requestAnimationFrame typewriter at an adaptive rate (chars/frame scales with
the pending backlog so it never lags the network); update only the one
streaming bubble per frame, snap to the full markdown render on finalize,
respect prefers-reduced-motion, and keep auto-scroll without fighting a
scrolled-up visitor.

Tests: markdown unit tests incl. XSS payloads (<script>, <img onerror>,
[x](javascript:), ![y](http://evil/x.png), <a onclick>); streaming reveal
unit tests (burst → full text, reduced-motion snap); e2e drives the real
shadow-DOM UI through the mock WS to assert <strong>/<li>/<a> render and no
<img>/<script> in the DOM.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...sanitized-markdown-and-smooth-streaming.md |  16 +
 e2e/repro-stream-mock.spec.ts                 | 153 ++++++++
 src/element.ts                                | 255 +++++++++---
 src/markdown.test.ts                          | 182 +++++++++
 src/markdown.ts                               | 368 ++++++++++++++++++
 src/streaming.test.ts                         | 114 ++++++
 src/styles.ts                                 |  44 +++
 7 files changed, 1085 insertions(+), 47 deletions(-)
 create mode 100644 .changeset/sanitized-markdown-and-smooth-streaming.md
 create mode 100644 src/markdown.test.ts
 create mode 100644 src/markdown.ts
 create mode 100644 src/streaming.test.ts

diff --git a/.changeset/sanitized-markdown-and-smooth-streaming.md b/.changeset/sanitized-markdown-and-smooth-streaming.md
new file mode 100644
index 0000000..5a9ca1d
--- /dev/null
+++ b/.changeset/sanitized-markdown-and-smooth-streaming.md
@@ -0,0 +1,16 @@
+---
+'@smooai/chat-widget': minor
+---
+
+Render sanitized Markdown in assistant replies and citation snippets, and smooth out the streaming reveal.
+
+**Sanitized Markdown rendering.** Assistant responses and citation snippets previously showed Markdown literally (`**bold**`, numbered lists, `[links](url)` rendered as raw text). They now render to formatted HTML through a tiny, safe-by-default renderer (`markdown.ts`) that:
+
+- escapes **all** text — raw `<script>`, `<img onerror=…>`, `<iframe>` etc. render as inert text, never markup;
+- **drops images entirely** (a scraped tracking pixel can't load) — `![alt](src)` becomes its alt text;
+- allows **only `http(s)` links** (`javascript:`/`data:`/relative fall back to plain text) with `target="_blank"` + `rel="noopener noreferrer nofollow"`;
+- emits only an allowlisted tag set (`p`, `br`, `strong`, `em`, `ul`/`ol`/`li`, `code`/`pre`, `a`, `blockquote`) and **downgrades headings** to bold lines so they fit a chat bubble.
+
+User bubbles stay plain text; mid-stream text stays plain (partial Markdown renders ugly) and only the final assistant turn is rendered as Markdown. Citation snippets are also cleaned first — leading page boilerplate (logo image/link, nav, whitespace) is trimmed and the excerpt is truncated to ~260 chars at a word boundary.
+
+**Smooth streaming reveal.** The assistant bubble no longer jumps in jerky, uneven chunks as `stream_token` bursts arrive. Incoming token text is buffered and revealed via a `requestAnimationFrame` typewriter at an adaptive rate (chars-per-frame scales with the pending backlog, so it never falls behind the network); only the single streaming bubble is updated per frame (no full list rebuild), and the final turn snaps to the full Markdown render. Respects `prefers-reduced-motion` (snaps instantly) and keeps auto-scroll without fighting a visitor who has scrolled up.
diff --git a/e2e/repro-stream-mock.spec.ts b/e2e/repro-stream-mock.spec.ts
index d10cdba..b669bc5 100644
--- a/e2e/repro-stream-mock.spec.ts
+++ b/e2e/repro-stream-mock.spec.ts
@@ -144,3 +144,156 @@ test('GLOBAL bundle streams a grounded turn end-to-end (real UI)', async ({ page
     expect(result.error, `controller error: ${result.error}`).toBeUndefined();
     expect(result.text ?? '').toContain('streamed reply');
 });
+
+// A markdown-rich reply that ALSO carries XSS payloads. The final assistant turn
+// must render the markdown to real `<strong>`/`<li>`/`<a>` elements while the
+// `<script>` / `<img onerror>` payloads must NOT produce live elements in the DOM.
+const MARKDOWN_REPLY = [
+    'Here is **bold** text and a [link](https://smoo.ai/docs).',
+    '',
+    '- first item',
+    '- second item',
+    '',
+    'And an inert payload: <script>alert(1)</script> <img src=x onerror=alert(1)> ![pixel](http://evil/x.png)',
+].join('\n');
+
+const MOCK_WS_MD = `
+(() => {
+  class MockWS {
+    constructor(url) {
+      this.url = url;
+      this.readyState = 0;
+      this._listeners = { open: [], message: [], close: [], error: [] };
+      setTimeout(() => { this.readyState = 1; this._emit('open', {}); }, 5);
+    }
+    addEventListener(type, fn) { (this._listeners[type] ||= []).push(fn); }
+    removeEventListener(type, fn) {
+      const a = this._listeners[type]; if (!a) return;
+      const i = a.indexOf(fn); if (i >= 0) a.splice(i, 1);
+    }
+    _emit(type, ev) { for (const fn of (this._listeners[type] || []).slice()) fn(ev); }
+    _msg(obj) { this._emit('message', { data: JSON.stringify(obj) }); }
+    send(raw) {
+      let frame; try { frame = JSON.parse(raw); } catch { return; }
+      const requestId = frame.requestId;
+      if (frame.action === 'create_conversation_session') {
+        this._msg({ type: 'immediate_response', requestId, status: 202,
+          data: { sessionId: 'sess-mock-md', agentId: frame.agentId } });
+        return;
+      }
+      if (frame.action === 'send_message') {
+        this._msg({ type: 'immediate_response', requestId, status: 202, data: {} });
+        const reply = ${JSON.stringify(MARKDOWN_REPLY)};
+        // Stream the reply in a couple of chunks, then finalize.
+        setTimeout(() => {
+          this._msg({ type: 'stream_token', requestId, token: reply.slice(0, 20) });
+          setTimeout(() => {
+            this._msg({ type: 'stream_token', requestId, token: reply.slice(20) });
+            setTimeout(() => {
+              this._msg({ type: 'eventual_response', requestId, status: 200, data: { data: {
+                response: { responseParts: [reply] },
+                citations: [{ id: 'c1', title: 'Our Work', score: 0.9, url: 'https://smoo.ai/work',
+                  snippet: '[![Logo](https://x/logo.png)](https://x/) # Our Work We build **great** things for clients across many industries.' }],
+              } } });
+            }, 5);
+          }, 5);
+        }, 5);
+        return;
+      }
+    }
+    close() { this.readyState = 3; this._emit('close', { code: 1000, reason: '' }); }
+  }
+  MockWS.CONNECTING = 0; MockWS.OPEN = 1; MockWS.CLOSING = 2; MockWS.CLOSED = 3;
+  window.WebSocket = MockWS;
+})();
+`;
+
+test('GLOBAL bundle renders sanitized markdown for the final assistant turn (real UI)', async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+    page.on('console', (m) => {
+        if (m.type() === 'error') pageErrors.push(`console.error: ${m.text()}`);
+    });
+
+    await page.addInitScript(MOCK_WS_MD);
+    await page.goto('about:blank');
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const out: Record<string, unknown> = {};
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as any).shadowRoot as ShadowRoot;
+            const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            for (let i = 0; i < 100; i++) {
+                const status = (root.querySelector('.status-text') as HTMLElement | null)?.textContent ?? '';
+                if (/ready|online/i.test(status)) break;
+                await sleep(50);
+            }
+            const input = root.querySelector('textarea') as HTMLTextAreaElement;
+            input.value = 'hi';
+            input.dispatchEvent(new Event('input', { bubbles: true }));
+            (root.querySelector('.send') as HTMLElement | null)?.click();
+
+            // Wait until the final (non-streaming, markdown) bubble has settled.
+            for (let i = 0; i < 120; i++) {
+                if (root.querySelector('.bubble.assistant.md strong')) break;
+                await sleep(50);
+            }
+
+            const md = root.querySelector('.bubble.assistant.md');
+            out.hasStrong = !!md?.querySelector('strong');
+            out.hasListItems = (md?.querySelectorAll('li').length ?? 0) >= 2;
+            const a = md?.querySelector('a') as HTMLAnchorElement | null;
+            out.linkHref = a?.getAttribute('href') ?? null;
+            out.linkRel = a?.getAttribute('rel') ?? null;
+            out.linkTarget = a?.getAttribute('target') ?? null;
+
+            // XSS: no live <script>/<img>/<iframe> anywhere in the shadow tree.
+            out.scriptCount = root.querySelectorAll('script').length;
+            out.imgCount = root.querySelectorAll('img').length;
+            out.iframeCount = root.querySelectorAll('iframe').length;
+            // No event-handler attributes survived on any element.
+            let onAttr = 0;
+            for (const node of Array.from(root.querySelectorAll('*'))) {
+                for (const attr of Array.from((node as Element).attributes)) {
+                    if (/^on/i.test(attr.name)) onAttr++;
+                }
+            }
+            out.onHandlerAttrs = onAttr;
+
+            // Citation snippet: cleaned (no logo image/link), rendered markdown.
+            const snip = root.querySelector('.src-snippet');
+            out.snippetText = snip?.textContent ?? '';
+            out.snippetHasImg = !!snip?.querySelector('img');
+            out.snippetHasStrong = !!snip?.querySelector('strong');
+            return out;
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    console.log('MD result:', JSON.stringify(result, null, 2));
+    expect(pageErrors, `page errors:\n${pageErrors.join('\n---\n')}`).toEqual([]);
+
+    // Markdown rendered to real elements.
+    expect(result.hasStrong, 'expected **bold** → <strong>').toBe(true);
+    expect(result.hasListItems, 'expected list → ≥2 <li>').toBe(true);
+    expect(result.linkHref).toBe('https://smoo.ai/docs');
+    expect(result.linkTarget).toBe('_blank');
+    expect(String(result.linkRel)).toContain('noopener');
+    expect(String(result.linkRel)).toContain('nofollow');
+
+    // XSS payloads neutralized — no live nodes, no handler attributes.
+    expect(result.scriptCount, 'no <script> may exist in the shadow tree').toBe(0);
+    expect(result.imgCount, 'no <img> may exist in the shadow tree').toBe(0);
+    expect(result.iframeCount).toBe(0);
+    expect(result.onHandlerAttrs, 'no on* handler attributes may survive').toBe(0);
+
+    // Citation snippet cleaned + rendered.
+    expect(result.snippetHasImg, 'snippet must drop the logo image').toBe(false);
+    expect(String(result.snippetText)).not.toContain('Logo');
+    expect(result.snippetHasStrong, 'snippet markdown should render').toBe(true);
+});
diff --git a/src/element.ts b/src/element.ts
index 88ce546..fb2dc59 100644
--- a/src/element.ts
+++ b/src/element.ts
@@ -18,6 +18,7 @@ import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config
 import { needsUserInfo, resolveConfig } from './config.js';
 import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, 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,6 +68,8 @@ 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;
@@ -95,6 +83,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 +111,7 @@ export class SmoothAgentChatElement extends HTMLElement {
 
     disconnectedCallback(): void {
         this.mounted = false;
+        this.resetReveal();
         this.controller?.disconnect();
         this.controller = null;
     }
@@ -186,8 +191,7 @@ export class SmoothAgentChatElement extends HTMLElement {
         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;
@@ -232,8 +236,9 @@ 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;
@@ -277,6 +282,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');
@@ -310,7 +318,7 @@ export class SmoothAgentChatElement extends HTMLElement {
         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();
@@ -449,10 +457,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 +530,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 +555,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 +733,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 +743,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 +796,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)) {
diff --git a/src/markdown.test.ts b/src/markdown.test.ts
new file mode 100644
index 0000000..2af17cb
--- /dev/null
+++ b/src/markdown.test.ts
@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest';
+import { cleanCitationSnippet, escapeHtml, renderMarkdown, safeHttpUrl } from './markdown.js';
+
+describe('safeHttpUrl', () => {
+    it('accepts absolute http(s) URLs and returns the normalized href', () => {
+        expect(safeHttpUrl('https://example.com/docs')).toBe('https://example.com/docs');
+        expect(safeHttpUrl('http://example.com')).toBe('http://example.com/');
+    });
+
+    it('rejects dangerous and non-absolute schemes', () => {
+        // eslint-disable-next-line no-script-url
+        expect(safeHttpUrl('javascript:alert(1)')).toBeNull();
+        expect(safeHttpUrl('data:text/html,<script>')).toBeNull();
+        expect(safeHttpUrl('vbscript:msgbox')).toBeNull();
+        expect(safeHttpUrl('/relative')).toBeNull();
+        expect(safeHttpUrl('')).toBeNull();
+        expect(safeHttpUrl(null)).toBeNull();
+    });
+});
+
+describe('escapeHtml', () => {
+    it('escapes the five HTML-significant characters', () => {
+        expect(escapeHtml(`<a href="x" o='y'>&`)).toBe('&lt;a href=&quot;x&quot; o=&#39;y&#39;&gt;&amp;');
+    });
+});
+
+describe('renderMarkdown — formatting', () => {
+    it('renders bold, italic, and inline code', () => {
+        expect(renderMarkdown('**bold**')).toBe('<p><strong>bold</strong></p>');
+        expect(renderMarkdown('_em_')).toBe('<p><em>em</em></p>');
+        expect(renderMarkdown('`x = 1`')).toBe('<p><code>x = 1</code></p>');
+    });
+
+    it('renders unordered lists', () => {
+        const html = renderMarkdown('- one\n- two\n- three');
+        expect(html).toBe('<ul><li>one</li><li>two</li><li>three</li></ul>');
+    });
+
+    it('renders ordered (numbered) lists', () => {
+        const html = renderMarkdown('1. first\n2. second');
+        expect(html).toBe('<ol><li>first</li><li>second</li></ol>');
+    });
+
+    it('renders safe http(s) links with target + hardened rel', () => {
+        const html = renderMarkdown('see [docs](https://smoo.ai/docs)');
+        expect(html).toContain('<a href="https://smoo.ai/docs" target="_blank" rel="noopener noreferrer nofollow">docs</a>');
+    });
+
+    it('downgrades headings to bold lines (no <h1>)', () => {
+        const html = renderMarkdown('# Big Title\n\n## Smaller');
+        expect(html).not.toMatch(/<h[1-6]/);
+        expect(html).toContain('<strong>Big Title</strong>');
+        expect(html).toContain('<strong>Smaller</strong>');
+    });
+
+    it('renders fenced code blocks', () => {
+        const html = renderMarkdown('```\nlet a = 1;\n```');
+        expect(html).toBe('<pre><code>let a = 1;</code></pre>');
+    });
+
+    it('renders blockquotes', () => {
+        const html = renderMarkdown('> quoted');
+        expect(html).toBe('<blockquote>quoted</blockquote>');
+    });
+
+    it('separates paragraphs on blank lines and soft-breaks within a paragraph', () => {
+        expect(renderMarkdown('a\nb\n\nc')).toBe('<p>a<br>b</p><p>c</p>');
+    });
+});
+
+describe('renderMarkdown — XSS / security bar', () => {
+    // The security property is that no *live* markup survives. Escaped entities
+    // (`&lt;img onerror=…&gt;`) are inert text and are perfectly fine — what must
+    // never happen is that a `<script>`/`<img onerror>` becomes a real element.
+    //
+    // Two layers of proof:
+    //  1. On the raw HTML string, no *unescaped* dangerous tag-open survives
+    //     (a real `<script`/`<img`/`<iframe` left intact would be a hole). This
+    //     deliberately checks for a tag-open (`<name`) — escaped output reads
+    //     `&lt;script` so it won't match.
+    //  2. Parse the output into a real DOM and assert the *live* tree carries no
+    //     forbidden elements, no event-handler attributes, and only http(s)
+    //     hrefs. This is the strongest check — it's what the browser actually
+    //     builds.
+    const assertInert = (html: string) => {
+        expect(html).not.toMatch(/<script/i);
+        expect(html).not.toMatch(/<img/i);
+        expect(html).not.toMatch(/<iframe/i);
+
+        const host = document.createElement('div');
+        host.innerHTML = html;
+        expect(host.querySelector('script, img, iframe, object, embed')).toBeNull();
+        for (const el of host.querySelectorAll('*')) {
+            for (const attr of el.attributes) {
+                expect(attr.name.toLowerCase()).not.toMatch(/^on/); // no event handlers
+                if (attr.name.toLowerCase() === 'href') {
+                    expect(attr.value.toLowerCase()).toMatch(/^https?:/);
+                }
+            }
+        }
+    };
+
+    it('escapes a raw <script> payload to inert text', () => {
+        const html = renderMarkdown('<script>alert(1)</script>');
+        assertInert(html);
+        expect(html).toContain('&lt;script&gt;');
+    });
+
+    it('escapes a raw <img onerror> payload', () => {
+        const html = renderMarkdown('<img src=x onerror=alert(1)>');
+        assertInert(html);
+        expect(html).toContain('&lt;img');
+    });
+
+    it('renders a markdown image as alt text only — never an <img>', () => {
+        const html = renderMarkdown('![y](http://evil/x.png)');
+        assertInert(html);
+        expect(html).not.toContain('evil');
+        expect(html).toContain('y');
+    });
+
+    it('strips a javascript: link to plain text (no anchor, no scheme)', () => {
+        // eslint-disable-next-line no-script-url
+        const html = renderMarkdown('[x](javascript:alert(1))');
+        assertInert(html);
+        expect(html).not.toContain('<a');
+        expect(html).toContain('x');
+    });
+
+    it('escapes a raw <a onclick=…> payload', () => {
+        const html = renderMarkdown('<a onclick="steal()">click</a>');
+        assertInert(html);
+        expect(html).toContain('&lt;a');
+    });
+
+    it('rejects a data: URL link', () => {
+        const html = renderMarkdown('[x](data:text/html,<script>alert(1)</script>)');
+        assertInert(html);
+        expect(html).not.toContain('<a');
+    });
+
+    it('escapes HTML smuggled inside link text and code spans', () => {
+        assertInert(renderMarkdown('[<img onerror=x>](https://ok.com)'));
+        assertInert(renderMarkdown('`<script>alert(1)</script>`'));
+    });
+
+    it('escapes HTML inside list items and headings', () => {
+        assertInert(renderMarkdown('- <script>alert(1)</script>'));
+        assertInert(renderMarkdown('# <img src=x onerror=alert(1)>'));
+    });
+});
+
+describe('cleanCitationSnippet', () => {
+    it('strips a leading logo link + image and trailing boilerplate', () => {
+        const raw = '[![Logo](https://x/logo.png)](https://x/) # Our Work We build great things for clients.';
+        const out = cleanCitationSnippet(raw);
+        expect(out).not.toContain('Logo');
+        expect(out).not.toContain('logo.png');
+        expect(out).not.toMatch(/^#/);
+        expect(out.startsWith('Our Work') || out.startsWith('We build')).toBe(true);
+    });
+
+    it('strips a bare leading image', () => {
+        expect(cleanCitationSnippet('![hero](https://x/h.png) Welcome to the site')).toBe('Welcome to the site');
+    });
+
+    it('collapses whitespace', () => {
+        expect(cleanCitationSnippet('a   b\n\n  c')).toBe('a b c');
+    });
+
+    it('truncates long text at a word boundary with an ellipsis', () => {
+        const long = 'word '.repeat(120).trim();
+        const out = cleanCitationSnippet(long);
+        expect(out.length).toBeLessThanOrEqual(262);
+        expect(out.endsWith('…')).toBe(true);
+        expect(out).not.toMatch(/\Sword…$/); // ended on a boundary, not mid-word
+    });
+
+    it('leaves an already-clean short snippet intact', () => {
+        expect(cleanCitationSnippet('A clean excerpt.')).toBe('A clean excerpt.');
+    });
+});
diff --git a/src/markdown.ts b/src/markdown.ts
new file mode 100644
index 0000000..22b923b
--- /dev/null
+++ b/src/markdown.ts
@@ -0,0 +1,368 @@
+/**
+ * A tiny, safe-by-default Markdown → HTML renderer for the chat widget.
+ *
+ * ## Why a hand-rolled renderer (and not markdown-it / snarkdown)?
+ *
+ * The widget renders **untrusted** text in two places: the assistant's reply
+ * (LLM output, which can echo attacker-supplied content) and citation snippets
+ * (raw scraped page chunks). Today both are written via `textContent`, so
+ * `**bold**`, numbered lists, and `[links](url)` show up literally. We want
+ * them rendered — without re-opening the XSS hole that `textContent` was
+ * guarding against.
+ *
+ * markdown-it with `html:false` is safe-by-default but ships ~30 kB min into
+ * what is an embeddable **global** bundle, where every kilobyte is on the host
+ * page's critical path. snarkdown is ~1 kB but emits raw HTML, so it would
+ * require bolting on a separate sanitizer. Instead, this renderer is
+ * **safe-by-construction**:
+ *
+ *   1. It is a *tokenizer*, not an HTML passthrough. It only ever emits a
+ *      fixed allowlist of tags (`p`, `br`, `strong`, `em`, `ul`/`ol`/`li`,
+ *      `code`/`pre`, `a`, `blockquote`). There is no code path that copies a
+ *      tag out of the input — a literal `<script>` in the input is treated as
+ *      plain text.
+ *   2. **Every** text run is HTML-escaped via {@link escapeHtml} before it
+ *      reaches the output. Raw `<`, `>`, `&`, `"`, `'` can never become markup.
+ *   3. **Images are dropped entirely** — `![alt](src)` renders as its alt text,
+ *      no `<img>` is ever produced (a scraped tracking pixel must not load).
+ *   4. **Links** are gated through {@link safeHttpUrl}: only absolute `http(s)`
+ *      URLs become anchors (with `target="_blank"` + a hardened `rel`);
+ *      `javascript:`/`data:`/relative/etc. fall back to plain (escaped) text.
+ *   5. **Headings** (`#`..`######`) are *downgraded* to bold lines — a full
+ *      `<h1>` is far too large inside a chat bubble or citation card.
+ *
+ * The output is a string of HTML that is only ever assigned to `innerHTML` of
+ * an element the caller controls; because of (1)–(4) it can only contain the
+ * allowlisted, attribute-sanitized tags.
+ *
+ * Supported subset (deliberately small):
+ *   - Paragraphs (blank-line separated) and hard/soft line breaks
+ *   - `**bold**` / `__bold__`, `*italic*` / `_italic_`
+ *   - `` `inline code` `` and fenced ``` ```code blocks``` ```
+ *   - `- ` / `* ` / `+ ` unordered lists, `1.` ordered lists
+ *   - `> ` blockquotes
+ *   - `[text](http(s)://url)` links (images dropped to alt text)
+ *   - `#`..`######` headings → bold line
+ */
+
+/** Escape the five HTML-significant characters so a text run can never be markup. */
+export 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;';
+        }
+    });
+}
+
+/**
+ * Return `url` only if it is a valid absolute `http(s)` URL, else `null`.
+ *
+ * SECURITY: link targets here originate from untrusted content (LLM output /
+ * scraped citation chunks). Allowing an arbitrary string as an `href` permits
+ * `javascript:`/`data:`/`vbscript:` URLs that execute on click — a stored-XSS
+ * vector. Only absolute http(s) links are rendered as anchors; anything else
+ * falls back to plain text upstream.
+ */
+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;
+    }
+}
+
+// ───────────────────────────── Inline rendering ─────────────────────────────
+
+/**
+ * Render the inline span grammar of a single line/segment to safe HTML.
+ *
+ * Order matters: code spans are extracted first (their contents are *not*
+ * further parsed), then images are stripped to alt text, then links, then
+ * emphasis. Every literal text run is escaped on the way out.
+ */
+function renderInline(input: string): string {
+    let out = '';
+    let i = 0;
+    const n = input.length;
+
+    // Accumulate escaped literal text, flushing on each recognized token.
+    let buf = '';
+    const flush = () => {
+        if (buf) {
+            out += escapeHtml(buf);
+            buf = '';
+        }
+    };
+
+    while (i < n) {
+        const ch = input[i]!;
+
+        // Inline code: `...` — contents are literal (escaped), no nested parsing.
+        if (ch === '`') {
+            const end = input.indexOf('`', i + 1);
+            if (end > i) {
+                flush();
+                out += `<code>${escapeHtml(input.slice(i + 1, end))}</code>`;
+                i = end + 1;
+                continue;
+            }
+        }
+
+        // Image: ![alt](src) — DROPPED. Emit only the (escaped) alt text; never
+        // produce an <img> (a scraped tracking pixel must not load).
+        if (ch === '!' && input[i + 1] === '[') {
+            const m = imageAt(input, i);
+            if (m) {
+                flush();
+                out += renderInline(m.alt); // alt may itself contain emphasis
+                i = m.end;
+                continue;
+            }
+        }
+
+        // Link: [text](href)
+        if (ch === '[') {
+            const m = linkAt(input, i);
+            if (m) {
+                flush();
+                const safe = safeHttpUrl(m.href);
+                const inner = renderInline(m.text);
+                if (safe) {
+                    out += `<a href="${escapeHtml(safe)}" target="_blank" rel="noopener noreferrer nofollow">${inner}</a>`;
+                } else {
+                    // Unsafe scheme → render as plain (already-escaped) text, no anchor.
+                    out += inner;
+                }
+                i = m.end;
+                continue;
+            }
+        }
+
+        // Bold: **...** or __...__
+        if ((ch === '*' && input[i + 1] === '*') || (ch === '_' && input[i + 1] === '_')) {
+            const marker = ch + ch;
+            const end = input.indexOf(marker, i + 2);
+            if (end > i + 1) {
+                flush();
+                out += `<strong>${renderInline(input.slice(i + 2, end))}</strong>`;
+                i = end + 2;
+                continue;
+            }
+        }
+
+        // Italic: *...* or _..._ (single marker, non-empty, not touching the other marker)
+        if (ch === '*' || ch === '_') {
+            const end = input.indexOf(ch, i + 1);
+            if (end > i + 1 && input[i + 1] !== ch) {
+                flush();
+                out += `<em>${renderInline(input.slice(i + 1, end))}</em>`;
+                i = end + 1;
+                continue;
+            }
+        }
+
+        buf += ch;
+        i++;
+    }
+
+    flush();
+    return out;
+}
+
+/** Parse a `[text](href)` link starting at `start` (`input[start] === '['`). */
+function linkAt(input: string, start: number): { text: string; href: string; end: number } | null {
+    const close = matchBracket(input, start);
+    if (close < 0 || input[close + 1] !== '(') return null;
+    const paren = input.indexOf(')', close + 2);
+    if (paren < 0) return null;
+    const text = input.slice(start + 1, close);
+    // href is the first whitespace-delimited token inside (...) — ignore any
+    // markdown "title" portion; we never render titles.
+    const href = input.slice(close + 2, paren).trim().split(/\s+/)[0] ?? '';
+    return { text, href, end: paren + 1 };
+}
+
+/** Parse a `![alt](src)` image starting at `start` (`input[start] === '!'`). */
+function imageAt(input: string, start: number): { alt: string; end: number } | null {
+    const link = linkAt(input, start + 1);
+    if (!link) return null;
+    return { alt: link.text, end: link.end };
+}
+
+/** Find the matching `]` for a `[` at `open`, honoring one level of nesting. */
+function matchBracket(input: string, open: number): number {
+    let depth = 0;
+    for (let i = open; i < input.length; i++) {
+        const c = input[i];
+        if (c === '[') depth++;
+        else if (c === ']') {
+            depth--;
+            if (depth === 0) return i;
+        }
+    }
+    return -1;
+}
+
+// ───────────────────────────── Block rendering ──────────────────────────────
+
+const UL_RE = /^\s*[-*+]\s+(.*)$/;
+const OL_RE = /^\s*\d+[.)]\s+(.*)$/;
+const HEADING_RE = /^\s{0,3}(#{1,6})\s+(.*)$/;
+const QUOTE_RE = /^\s*>\s?(.*)$/;
+const FENCE_RE = /^\s*(`{3,}|~{3,})\s*(.*)$/;
+
+/**
+ * Render a full Markdown string to safe HTML.
+ *
+ * @returns a string containing only the allowlisted tags described in the
+ * module doc. Safe to assign to `innerHTML` of a caller-owned element.
+ */
+export function renderMarkdown(src: string): string {
+    const lines = src.replace(/\r\n?/g, '\n').split('\n');
+    const out: string[] = [];
+
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i]!;
+
+        // Fenced code block: ```lang ... ```
+        const fence = FENCE_RE.exec(line);
+        if (fence) {
+            const marker = fence[1]!;
+            const body: string[] = [];
+            i++;
+            while (i < lines.length && !lines[i]!.trimStart().startsWith(marker)) {
+                body.push(lines[i]!);
+                i++;
+            }
+            if (i < lines.length) i++; // consume closing fence
+            out.push(`<pre><code>${escapeHtml(body.join('\n'))}</code></pre>`);
+            continue;
+        }
+
+        // Blank line → paragraph boundary.
+        if (line.trim() === '') {
+            i++;
+            continue;
+        }
+
+        // Heading → downgraded to a bold line (an <h1> is too big in a bubble).
+        const heading = HEADING_RE.exec(line);
+        if (heading) {
+            out.push(`<p><strong>${renderInline(heading[2]!)}</strong></p>`);
+            i++;
+            continue;
+        }
+
+        // Unordered / ordered list — consume the contiguous run.
+        if (UL_RE.test(line) || OL_RE.test(line)) {
+            const ordered = OL_RE.test(line) && !UL_RE.test(line);
+            const re = ordered ? OL_RE : UL_RE;
+            const items: string[] = [];
+            while (i < lines.length) {
+                const m = re.exec(lines[i]!);
+                if (!m) break;
+                items.push(`<li>${renderInline(m[1]!)}</li>`);
+                i++;
+            }
+            out.push(`<${ordered ? 'ol' : 'ul'}>${items.join('')}</${ordered ? 'ol' : 'ul'}>`);
+            continue;
+        }
+
+        // Blockquote — consume the contiguous run.
+        if (QUOTE_RE.test(line)) {
+            const quoted: string[] = [];
+            while (i < lines.length) {
+                const m = QUOTE_RE.exec(lines[i]!);
+                if (!m) break;
+                quoted.push(m[1]!);
+                i++;
+            }
+            out.push(`<blockquote>${renderInline(quoted.join('\n')).replace(/\n/g, '<br>')}</blockquote>`);
+            continue;
+        }
+
+        // Paragraph — gather consecutive non-blank, non-block lines; soft breaks → <br>.
+        const para: string[] = [];
+        while (i < lines.length) {
+            const l = lines[i]!;
+            if (
+                l.trim() === '' ||
+                FENCE_RE.test(l) ||
+                HEADING_RE.test(l) ||
+                UL_RE.test(l) ||
+                OL_RE.test(l) ||
+                QUOTE_RE.test(l)
+            ) {
+                break;
+            }
+            para.push(l);
+            i++;
+        }
+        out.push(`<p>${renderInline(para.join('\n')).replace(/\n/g, '<br>')}</p>`);
+    }
+
+    return out.join('');
+}
+
+// ───────────────────────── Citation-snippet cleanup ─────────────────────────
+
+const SNIPPET_MAX = 260;
+
+/**
+ * Clean a raw scraped citation snippet into a short, readable excerpt.
+ *
+ * Scraped chunks frequently begin with page boilerplate — a logo image wrapped
+ * in a link, standalone nav, repeated whitespace — e.g.
+ * `[![Logo](…)](…) # Our Work We build…`. The source itself is already linked
+ * from the citation card, so the snippet only needs to be a clean teaser.
+ *
+ * Steps:
+ *   1. Strip a leading image / logo-link (`[![…](…)](…)` or `![…](…)`).
+ *   2. Drop a leading standalone heading marker (`#`/`##`).
+ *   3. Collapse all runs of whitespace to single spaces.
+ *   4. Truncate to ~{@link SNIPPET_MAX} chars at a word boundary, adding `…`.
+ *
+ * The result is still rendered through {@link renderMarkdown} downstream, so any
+ * remaining inline markup (bold/links) stays safe.
+ */
+export function cleanCitationSnippet(raw: string): string {
+    let s = raw ?? '';
+
+    // Repeatedly peel leading boilerplate tokens.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const before = s;
+        // Leading linked image: [![alt](imgsrc)](href)
+        s = s.replace(/^\s*\[!\[[^\]]*\]\([^)]*\)\]\([^)]*\)\s*/, '');
+        // Leading bare image: ![alt](src)
+        s = s.replace(/^\s*!\[[^\]]*\]\([^)]*\)\s*/, '');
+        // Leading heading marker(s): "# ", "## " (keep the heading text)
+        s = s.replace(/^\s*#{1,6}\s+/, '');
+        if (s !== before) changed = true;
+    }
+
+    // Collapse whitespace.
+    s = s.replace(/\s+/g, ' ').trim();
+
+    // Truncate at a word boundary.
+    if (s.length > SNIPPET_MAX) {
+        const cut = s.slice(0, SNIPPET_MAX);
+        const lastSpace = cut.lastIndexOf(' ');
+        s = (lastSpace > SNIPPET_MAX * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd() + '…';
+    }
+
+    return s;
+}
diff --git a/src/streaming.test.ts b/src/streaming.test.ts
new file mode 100644
index 0000000..a6ec1ea
--- /dev/null
+++ b/src/streaming.test.ts
@@ -0,0 +1,114 @@
+/**
+ * Unit tests for the smooth streaming reveal (rAF typewriter) in element.ts.
+ *
+ * We mount the real custom element, then drive its private `handleMessages`
+ * hook (the same entry point the ConversationController calls on every
+ * `stream_token`). A fake `requestAnimationFrame` lets us pump frames
+ * deterministically and assert the reveal converges on the full text with no
+ * dropped/duplicated characters, and that reduced-motion snaps instantly.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ChatMessage } from './conversation.js';
+import { defineChatWidget, ELEMENT_TAG } from './element.js';
+
+interface RevealHarness extends HTMLElement {
+    handleMessages(messages: ChatMessage[], greeting: string): void;
+}
+
+// Deterministic rAF: queue callbacks, flush on demand.
+let rafQueue: FrameRequestCallback[] = [];
+function flushFrames(n = 200): void {
+    for (let i = 0; i < n && rafQueue.length; i++) {
+        const cbs = rafQueue;
+        rafQueue = [];
+        for (const cb of cbs) cb(performance.now());
+    }
+}
+
+function assistant(id: string, text: string, streaming: boolean): ChatMessage {
+    return { id, role: 'assistant', text, streaming };
+}
+
+function mount(reducedMotion: boolean): RevealHarness {
+    vi.stubGlobal('matchMedia', (q: string) => ({
+        matches: reducedMotion && /reduced-motion/.test(q),
+        media: q,
+        addEventListener() {},
+        removeEventListener() {},
+    }));
+    defineChatWidget();
+    const el = document.createElement(ELEMENT_TAG) as RevealHarness;
+    el.setAttribute('endpoint', 'wss://e/ws');
+    el.setAttribute('agent-id', 'a1');
+    el.setAttribute('greeting', '');
+    document.body.appendChild(el);
+    return el;
+}
+
+function bubbleText(el: HTMLElement): string {
+    const b = el.shadowRoot!.querySelector('.bubble.assistant');
+    return b?.textContent ?? '';
+}
+
+describe('smooth streaming reveal', () => {
+    beforeEach(() => {
+        rafQueue = [];
+        vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+            rafQueue.push(cb);
+            return rafQueue.length;
+        });
+        vi.stubGlobal('cancelAnimationFrame', () => {});
+    });
+
+    afterEach(() => {
+        document.body.innerHTML = '';
+        vi.unstubAllGlobals();
+    });
+
+    it('reveals the complete final text across a burst of tokens (no dropped/dup chars)', () => {
+        const el = mount(false);
+        const full = 'Hello, this is a streamed reply that arrives in uneven bursts of tokens.';
+
+        // Simulate variable-size bursts: empty (typing) → growing chunks.
+        el.handleMessages([assistant('m1', '', true)], '');
+        el.handleMessages([assistant('m1', 'Hello, this', true)], '');
+        el.handleMessages([assistant('m1', 'Hello, this is a streamed reply', true)], '');
+        el.handleMessages([assistant('m1', full, true)], '');
+
+        // Pump frames until the reveal catches up to the buffered target.
+        flushFrames();
+        expect(bubbleText(el)).toBe(full);
+
+        // Finalize → markdown render snaps to the full text, no loss.
+        el.handleMessages([assistant('m1', full, false)], '');
+        const finalBubble = el.shadowRoot!.querySelector('.bubble.assistant.md');
+        expect(finalBubble?.textContent).toBe(full);
+    });
+
+    it('mid-reveal does not show more than the buffered target', () => {
+        const el = mount(false);
+        el.handleMessages([assistant('m1', '', true)], '');
+        el.handleMessages([assistant('m1', 'abcdefghij', true)], '');
+        // After a single frame, displayed length must never exceed the target.
+        flushFrames(1);
+        const shown = bubbleText(el);
+        expect('abcdefghij'.startsWith(shown)).toBe(true);
+        expect(shown.length).toBeLessThanOrEqual(10);
+    });
+
+    it('reduced-motion snaps to the full text immediately (no animation needed)', () => {
+        const el = mount(true);
+        el.handleMessages([assistant('m1', '', true)], '');
+        el.handleMessages([assistant('m1', 'Snap to full instantly', true)], '');
+        // No frames pumped — reduced-motion must have shown everything already.
+        expect(bubbleText(el)).toBe('Snap to full instantly');
+        expect(rafQueue.length).toBe(0);
+    });
+
+    it('keeps the blinking cursor on the streaming bubble', () => {
+        const el = mount(false);
+        el.handleMessages([assistant('m1', '', true)], '');
+        el.handleMessages([assistant('m1', 'partial', true)], '');
+        expect(el.shadowRoot!.querySelector('.bubble.assistant.cursor')).not.toBeNull();
+    });
+});
diff --git a/src/styles.ts b/src/styles.ts
index b5a6a88..d19c802 100644
--- a/src/styles.ts
+++ b/src/styles.ts
@@ -327,6 +327,50 @@ export function buildStyles(theme: ResolvedTheme, mode: ChatWidgetMode = 'popove
 }
 @keyframes sac-blink { to { opacity: 0 } }
 
+/* ─────────────── Rendered markdown (assistant bubbles / snippets) ─────────── */
+/* The renderer (markdown.ts) emits a small allowlisted set of tags; these rules
+   keep them legible inside the tight Aurora-Glass bubble + citation card. */
+/* Block-level markdown drives its own spacing/wrapping, so opt out of the
+   bubble's pre-wrap (which would otherwise add stray blank lines). */
+.bubble.md { white-space: normal; }
+.md > :first-child { margin-top: 0; }
+.md > :last-child { margin-bottom: 0; }
+.md p { margin: 0 0 8px; }
+.md ul, .md ol { margin: 6px 0 8px; padding-left: 20px; }
+.md li { margin: 2px 0; }
+.md li::marker { color: color-mix(in srgb, var(--sac-primary) 75%, transparent); }
+.md a {
+    color: color-mix(in srgb, var(--sac-primary) 92%, #fff);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    word-break: break-word;
+}
+.md a:hover { text-decoration: none; }
+.md strong { font-weight: 700; }
+.md em { font-style: italic; }
+.md code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: .9em;
+    padding: 1px 5px;
+    border-radius: 5px;
+    background: color-mix(in srgb, var(--sac-text) 10%, transparent);
+}
+.md pre {
+    margin: 6px 0 8px;
+    padding: 9px 11px;
+    border-radius: 9px;
+    overflow-x: auto;
+    background: color-mix(in srgb, var(--sac-text) 9%, transparent);
+    border: 1px solid color-mix(in srgb, var(--sac-text) 8%, transparent);
+}
+.md pre code { padding: 0; background: none; font-size: 12px; line-height: 1.45; }
+.md blockquote {
+    margin: 6px 0;
+    padding: 2px 0 2px 11px;
+    border-left: 2px solid color-mix(in srgb, var(--sac-primary) 55%, transparent);
+    color: color-mix(in srgb, var(--sac-text) 78%, transparent);
+}
+
 /* Full-page: center the conversation in a readable column. */
 .panel.fullpage .messages { padding: 26px 20px; }
 .panel.fullpage .row { max-width: 760px; width: 100%; margin-left: auto; margin-right: auto; }