@veluai/velu 0.2.13 → 0.2.15

package/runtime/velu-ui/components/Chatbot.jsx

@@ -1,885 +1,885 @@
-import React, { useState, useRef, useEffect, useCallback } from 'react';
-import resolveIcon from '../lib/resolveIcon.jsx';
-import Stack from '../primitives/Stack.jsx';
-import Cluster from '../primitives/Cluster.jsx';
-
-/**
- * Chatbot — the Velu "Ask AI" panel. A right-side slide-out: header +
- * scrolling message body + composer. Ported from the Claude-Design
- * "Velu Chatbot" handoff (rich variant), retokenized onto velu-ui's
- * scale so it themes for free via [data-theme].
- *
- *   <Chatbot
- *     open={chatOpen}
- *     seedQuestion={question}      // first message — sent on open
- *     onClose={() => setChatOpen(false)}
- *     ask={askDocs}                // OPTIONAL — real backend (see below)
- *     onFeedback={(id, v) => …}    // OPTIONAL — 👍/👎 for a message
- *   />
- *
- * Slide: the panel is fixed to the inline-end edge; `open` toggles a
- * `translateX` between fully off-screen and 0. Width is the
- * `--vchat-width` variable (default 24rem ≈ the design's 384px).
- *
- * Backend seam (mirrors Search.jsx's injectable `search` prop):
- *   ask(prompt, { conversationId, signal }) → AsyncIterable<AskEvent>
- *   AskEvent = {
- *     delta?: string,            // text chunk to append (streamed)
- *     citations?: Source[],      // [{ num, title, path, url }] — replaces sources
- *     messageId?: string,        // assistant message id (for feedback)
- *     conversationId?: string,   // threaded across turns
- *   }
- * When `ask` is omitted the panel falls back to a canned, fake-streamed
- * demo answer (so dev preview / offline still shows the experience).
- */
-
-/* ── Brand mark — the Velu double-hook logo ─────────────────────────── */
-// `size` is the glyph height; width derives from the 32:24 viewBox.
-function VeluMark({ size = 'var(--icon-size-lg)' }) {
-  return (
-    <svg
-      className="velu-chatbot__mark"
-      viewBox="0 0 32 24"
-      fill="currentColor"
-      aria-hidden="true"
-      style={{ width: `calc(${size} * (32 / 24))`, height: size }}
-    >
-      <path d="M 29.656 14.153 C 29.574 14.562 29.351 14.929 29.025 15.193 C 28.699 15.457 28.291 15.601 27.869 15.601 L 21.37 15.601 C 20.534 15.601 19.805 16.163 19.603 16.964 L 18.167 22.637 C 18.068 23.026 17.841 23.372 17.521 23.619 C 17.2 23.866 16.805 24 16.399 24 L 10.438 24 C 10.161 24 9.888 23.938 9.639 23.818 C 9.39 23.698 9.172 23.524 9.001 23.308 C 8.831 23.092 8.712 22.841 8.655 22.574 C 8.598 22.306 8.603 22.029 8.67 21.764 L 10.189 15.764 C 10.287 15.374 10.515 15.029 10.835 14.782 C 11.155 14.535 11.55 14.401 11.956 14.4 L 18.393 14.4 C 19.262 14.4 20.01 13.795 20.18 12.953 L 22.388 2.048 C 22.471 1.639 22.694 1.272 23.019 1.008 C 23.345 0.744 23.754 0.6 24.175 0.6 L 30.177 0.6 C 30.447 0.6 30.713 0.659 30.957 0.773 C 31.201 0.886 31.416 1.052 31.587 1.258 C 31.758 1.464 31.881 1.705 31.946 1.964 C 32.011 2.222 32.017 2.492 31.964 2.753 L 29.656 14.153 Z M 9.611 13.554 C 9.528 13.962 9.305 14.329 8.979 14.593 C 8.653 14.857 8.245 15.001 7.824 15.001 L 1.823 15.001 C 1.553 15.001 1.287 14.942 1.043 14.828 C 0.799 14.714 0.584 14.548 0.413 14.342 C 0.242 14.136 0.119 13.895 0.054 13.637 C -0.011 13.378 -0.017 13.109 0.036 12.848 L 2.344 1.447 C 2.426 1.039 2.649 0.672 2.975 0.408 C 3.301 0.144 3.709 0 4.131 0 L 10.132 0 C 10.402 0 10.668 0.059 10.912 0.173 C 11.155 0.287 11.371 0.453 11.541 0.659 C 11.712 0.865 11.835 1.106 11.9 1.364 C 11.965 1.623 11.972 1.892 11.919 2.153 L 9.611 13.553 L 9.611 13.554 Z" />
-    </svg>
-  );
-}
-
-/* ── "Thinking" loader — 3x3 grid of squares, opacity wave sweeps the
-   anti-diagonal so it ripples top-left → bottom-right. ─────────────── */
-function BlocksWave() {
-  const cells = [
-    [1, 1, 0], [8.33, 1, 1], [15.66, 1, 2],
-    [1, 8.33, 1], [8.33, 8.33, 2], [15.66, 8.33, 3],
-    [1, 15.66, 2], [8.33, 15.66, 3], [15.66, 15.66, 4],
-  ];
-  return (
-    <svg className="velu-chatbot__wave" viewBox="0 0 24 24" aria-hidden="true">
-      {cells.map(([x, y, cell], i) => (
-        <rect key={i} x={x} y={y} width="7.33" height="7.33" data-cell={cell} />
-      ))}
-    </svg>
-  );
-}
-
-/* ── Demo data ──────────────────────────────────────────────────────── */
-const SUGGESTIONS = [
-  { label: 'How do I set up GitHub sync?', icon: 'github' },
-  { label: 'Customize the look of my docs site', icon: 'book' },
-  { label: 'Configure AI search ranking', icon: 'sparkles' },
-  { label: 'Quickstart in under five minutes', icon: 'rocket' },
-];
-
-const HISTORY = [
-  { id: 'h1', title: 'Setting up GitHub sync', when: 'Today, 10:24' },
-  { id: 'h2', title: 'Custom theme tokens & dark mode', when: 'Today, 09:11' },
-  { id: 'h3', title: 'Configure AI search ranking', when: 'Yesterday' },
-  { id: 'h4', title: 'Embed a Mermaid diagram in MDX', when: 'Yesterday' },
-  { id: 'h5', title: 'Why are my callouts missing icons?', when: 'Apr 28' },
-  { id: 'h6', title: 'Quickstart — minimum site config', when: 'Apr 27' },
-];
-
-const SOURCES = [
-  { num: 1, title: 'GitHub & GitLab Sync', path: 'docs/integrations/github-sync.md' },
-  { num: 2, title: 'Site Settings — Repositories', path: 'docs/your-docs-site/site-settings.md' },
-  { num: 3, title: 'AI-native Documentation', path: 'docs/get-started/ai-native.md' },
-];
-
-/* Canned answer — segments interleave text, inline `code`, and citation
-   markers. The same answer is returned for any prompt (demo). */
-function buildAnswer() {
-  return {
-    segments: [
-      { t: 'Velu syncs documentation directly with GitHub and GitLab — every push to a connected repository updates the live docs site within seconds.' },
-      { cite: 1 },
-      { t: ' To set it up:\n\n1. Open ' },
-      { code: 'Site Settings → Repositories' },
-      { t: ' and click ' },
-      { code: 'Connect repository' },
-      { t: '.\n2. Authorize the Velu app on the org that owns the repo.\n3. Pick a branch (default ' },
-      { code: 'main' },
-      { t: ') and a docs root path.' },
-      { cite: 2 },
-      { t: '\n\nVelu watches changes to ' },
-      { code: '.md' },
-      { t: ' and ' },
-      { code: '.mdx' },
-      { t: ' files and re-indexes the site automatically.' },
-      { cite: 3 },
-    ],
-    sources: SOURCES,
-    followups: [
-      'How do I preview pull-request changes?',
-      'Can I sync from a monorepo subdirectory?',
-      'What about private repositories?',
-    ],
-  };
-}
-
-/* Real-backend path: turn the accumulated answer TEXT into the same token
-   shape `renderStream` consumes. The assistant streams plain text with inline
-   `code` spans and bracketed citation markers ([1], [2]); split those out so
-   they render as <code> and citation chips, exactly like the canned path. */
-function textToTokens(text) {
-  const tokens = [];
-  const re = /(`[^`]*`|\[\d+\])/g;
-  let last = 0;
-  let m;
-  while ((m = re.exec(text)) !== null) {
-    if (m.index > last) tokens.push({ kind: 't', v: text.slice(last, m.index) });
-    const tok = m[0];
-    if (tok[0] === '`') tokens.push({ kind: 'code', v: tok.slice(1, -1) });
-    else tokens.push({ kind: 'cite', n: Number(tok.slice(1, -1)) });
-    last = re.lastIndex;
-  }
-  if (last < text.length) tokens.push({ kind: 't', v: text.slice(last) });
-  return tokens;
-}
-
-/* Plain-text of an answer (for the Copy action). */
-function tokensToPlain(tokens) {
-  return tokens
-    .map((tk) => (tk.kind === 'cite' ? `[${tk.n}]` : tk.v))
-    .join('')
-    .trim();
-}
-
-/* Flatten an answer into a stream of small tokens for incremental render. */
-function tokenizeAnswer(answer) {
-  const tokens = [];
-  for (const seg of answer.segments) {
-    if (seg.cite != null) { tokens.push({ kind: 'cite', n: seg.cite }); continue; }
-    if (seg.code != null) { tokens.push({ kind: 'code', v: seg.code }); continue; }
-    const parts = seg.t.match(/\S+\s*|\s+/g) || [seg.t];
-    for (const p of parts) tokens.push({ kind: 't', v: p });
-  }
-  return tokens;
-}
-
-/* A citation's in-site target. Real backend sources carry a `url` (and `path`
-   is a route like "/essentials/code"); the demo's `path` is a fake file path,
-   so those stay inert. */
-function sourceHref(s) {
-  if (s?.url) return s.url;
-  if (s?.path && s.path.startsWith('/')) return s.path;
-  return null;
-}
-
-/* A readable label for a source: the section heading if present, else a title
-   derived from the route (e.g. "/essentials/settings" → "Settings"). */
-function citeTitle(s) {
-  if (s?.title) return s.title;
-  const path = (s?.path || '').replace(/[#?].*$/, '');
-  const seg = path.split('/').filter(Boolean).pop();
-  if (!seg) return 'Documentation';
-  return seg.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-/* Source click: SPA-navigate same-origin targets via onNavigate (keeps the chat
-   panel open + scrolls to the heading); otherwise let the <a href> navigate. */
-function onSourceClick(e, s, onNavigate) {
-  const href = sourceHref(s);
-  if (!href) { e.preventDefault(); return; }
-  if (!onNavigate) return; // no SPA hook → let the browser follow the href
-  try {
-    const u = new URL(href, window.location.origin);
-    if (u.origin === window.location.origin) {
-      e.preventDefault();
-      onNavigate(u.pathname + u.search + u.hash);
-    }
-  } catch { /* malformed — fall back to href */ }
-}
-
-/* Render partial tokens as paragraphs (split on \n\n, single \n → <br>). */
-function renderStream(tokens, sources, onNavigate) {
-  const paragraphs = [[]];
-  for (const tk of tokens) {
-    if (tk.kind === 't' && tk.v.includes('\n\n')) {
-      const split = tk.v.split('\n\n');
-      paragraphs[paragraphs.length - 1].push({ kind: 't', v: split[0] });
-      for (let i = 1; i < split.length; i++) {
-        paragraphs.push([]);
-        if (split[i]) paragraphs[paragraphs.length - 1].push({ kind: 't', v: split[i] });
-      }
-    } else {
-      paragraphs[paragraphs.length - 1].push(tk);
-    }
-  }
-  return paragraphs.map((para, pi) => (
-    <p key={pi}>
-      {para.map((tk, i) => {
-        if (tk.kind === 'cite') {
-          const src = sources?.find((s) => s.num === tk.n);
-          return (
-            <a
-              key={i}
-              className="velu-chatbot__cite"
-              href={sourceHref(src) || '#'}
-              onClick={(e) => onSourceClick(e, src, onNavigate)}
-              title={citeTitle(src)}
-            >
-              {tk.n}
-            </a>
-          );
-        }
-        if (tk.kind === 'code') return <code key={i}>{tk.v}</code>;
-        const lines = tk.v.split('\n');
-        return lines.map((line, li) => (
-          <React.Fragment key={`${i}-${li}`}>
-            {li > 0 && <br />}
-            {line}
-          </React.Fragment>
-        ));
-      })}
-    </p>
-  ));
-}
-
-/* ── Header ─────────────────────────────────────────────────────────── */
-function ChatHeader({ onClose, onNew, onHistory, historyOpen }) {
-  return (
-    <Cluster
-      space="var(--s-2)"
-      justify="space-between"
-      align="center"
-      className="velu-chatbot__header"
-    >
-      <Cluster space="var(--s-2)" align="center">
-        <VeluMark />
-        <span className="velu-chatbot__brand">
-          <span className="velu-chatbot__brand-name">Velu</span>
-          <span className="velu-chatbot__brand-sep">/</span>
-          <span className="velu-chatbot__brand-title">Ask AI</span>
-        </span>
-      </Cluster>
-      <Cluster space="var(--s-5)" align="center">
-        <button
-          type="button"
-          className={`velu-chatbot__iconbtn${historyOpen ? ' is-active' : ''}`}
-          aria-label="History"
-          onClick={onHistory}
-        >
-          {resolveIcon('history', { size: '1em' })}
-        </button>
-        <button
-          type="button"
-          className="velu-chatbot__iconbtn"
-          aria-label="New chat"
-          onClick={onNew}
-        >
-          {resolveIcon('plus', { size: '1em' })}
-        </button>
-        <button
-          type="button"
-          className="velu-chatbot__iconbtn"
-          aria-label="Close"
-          onClick={onClose}
-        >
-          {resolveIcon('x', { size: '1em' })}
-        </button>
-      </Cluster>
-    </Cluster>
-  );
-}
-
-/* ── History overlay ────────────────────────────────────────────────── */
-
-/* "Today, 10:24" / "Yesterday" / "Apr 28" for a conversation timestamp. */
-function whenLabel(iso) {
-  if (!iso) return '';
-  const d = new Date(iso);
-  if (Number.isNaN(d.getTime())) return '';
-  const startOfDay = (x) => new Date(x.getFullYear(), x.getMonth(), x.getDate());
-  const days = Math.round((startOfDay(new Date()) - startOfDay(d)) / 86400000);
-  if (days <= 0) {
-    return `Today, ${d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}`;
-  }
-  if (days === 1) return 'Yesterday';
-  return d.toLocaleDateString([], { month: 'short', day: 'numeric' });
-}
-
-function HistoryPanel({ items, loading, onPick, onClose }) {
-  return (
-    <div className="velu-chatbot__history">
-      <Cluster
-        space="var(--s-2)"
-        justify="space-between"
-        align="center"
-        className="velu-chatbot__history-head"
-      >
-        <span className="velu-chatbot__eyebrow">Recent chats</span>
-        <button
-          type="button"
-          className="velu-chatbot__iconbtn"
-          aria-label="Close history"
-          onClick={onClose}
-        >
-          {resolveIcon('x', { size: '1em' })}
-        </button>
-      </Cluster>
-      <Stack as="div" space="var(--s-5)" className="velu-chatbot__history-list">
-        {loading ? (
-          <span className="velu-chatbot__history-empty">Loading…</span>
-        ) : items.length === 0 ? (
-          <span className="velu-chatbot__history-empty">No conversations yet.</span>
-        ) : (
-          items.map((h) => (
-            <button
-              key={h.id}
-              type="button"
-              className="velu-chatbot__history-item"
-              onClick={() => onPick(h)}
-            >
-              <span className="velu-chatbot__history-item-title">{h.title}</span>
-              <span className="velu-chatbot__history-item-when">{h.when}</span>
-            </button>
-          ))
-        )}
-      </Stack>
-    </div>
-  );
-}
-
-/* ── Welcome / empty state ──────────────────────────────────────────── */
-function Welcome({ onPick, suggestions }) {
-  // Site-specific starter questions (velu.json assistant.suggestions, or
-  // publish-time generated); the canned demo list is the dev-preview fallback.
-  const items = suggestions?.length
-    ? suggestions.map((label) => ({ label, icon: 'sparkles' }))
-    : SUGGESTIONS;
-  return (
-    <Stack space="var(--s0)" className="velu-chatbot__welcome">
-      <p className="velu-chatbot__welcome-hi">Ask anything about the docs.</p>
-      <span className="velu-chatbot__eyebrow">Suggested</span>
-      <Stack space="var(--s-4)">
-        {items.map((s, i) => (
-          <button
-            key={i}
-            type="button"
-            className="velu-chatbot__suggest"
-            onClick={() => onPick(s.label)}
-          >
-            <Cluster space="var(--s-2)" align="center">
-              {resolveIcon(s.icon, { size: '1em' })}
-              <span>{s.label}</span>
-            </Cluster>
-            {resolveIcon('arrow-right', { size: '1em' })}
-          </button>
-        ))}
-      </Stack>
-    </Stack>
-  );
-}
-
-/* ── Messages ───────────────────────────────────────────────────────── */
-function UserMsg({ text }) {
-  return (
-    <div className="velu-chatbot__msg velu-chatbot__msg--user">
-      <div className="velu-chatbot__bubble">{text}</div>
-    </div>
-  );
-}
-
-function AiMsg({
-  tokens,
-  sources,
-  followups,
-  streaming,
-  onFollowup,
-  messageId,
-  onFeedback,
-  onNavigate,
-}) {
-  const thinking = tokens.length === 0;
-  const [vote, setVote] = useState(null); // 'up' | 'down' | null
-  const [copied, setCopied] = useState(false);
-
-  const onAction = (ic) => {
-    if (ic === 'copy') {
-      try {
-        navigator.clipboard?.writeText(tokensToPlain(tokens));
-        setCopied(true);
-        setTimeout(() => setCopied(false), 1400);
-      } catch {
-        /* clipboard blocked — no-op */
-      }
-      return;
-    }
-    if (ic === 'thumbs-up' || ic === 'thumbs-down') {
-      const v = ic === 'thumbs-up' ? 'up' : 'down';
-      const next = vote === v ? null : v; // toggle off if re-clicked
-      setVote(next);
-      onFeedback?.(messageId, next); // null = retract
-    }
-  };
-  return (
-    <div className="velu-chatbot__msg velu-chatbot__msg--ai">
-      <Cluster
-        space="var(--s-3)"
-        align="center"
-        className={`velu-chatbot__role${thinking ? ' is-thinking' : ''}`}
-      >
-        {thinking ? <BlocksWave /> : resolveIcon('sparkles', { size: '1em' })}
-        <span>{thinking ? 'Velu is thinking' : 'Velu'}</span>
-      </Cluster>
-
-      {!thinking && (
-        <div className="velu-chatbot__answer">
-          {renderStream(tokens, sources, onNavigate)}
-          {streaming && <span className="velu-chatbot__caret" />}
-
-          {!streaming && sources?.length > 0 && (
-            <Stack space="var(--s-4)" className="velu-chatbot__sources">
-              <span className="velu-chatbot__eyebrow">Sources</span>
-              {sources.map((s) => (
-                <a
-                  key={s.num}
-                  className="velu-chatbot__source"
-                  href={sourceHref(s) || '#'}
-                  onClick={(e) => onSourceClick(e, s, onNavigate)}
-                >
-                  <span className="velu-chatbot__source-num">{s.num}</span>
-                  <span className="velu-chatbot__source-meta">
-                    <span className="velu-chatbot__source-title">{citeTitle(s)}</span>
-                    <span className="velu-chatbot__source-path">{s.path}</span>
-                  </span>
-                </a>
-              ))}
-            </Stack>
-          )}
-
-          {!streaming && followups?.length > 0 && (
-            <Stack space="var(--s-4)" className="velu-chatbot__followups">
-              <span className="velu-chatbot__eyebrow">Follow up</span>
-              {followups.map((f, i) => (
-                <button
-                  key={i}
-                  type="button"
-                  className="velu-chatbot__followup"
-                  onClick={() => onFollowup(f)}
-                >
-                  <span>{f}</span>
-                  {resolveIcon('arrow-right', { size: '1em' })}
-                </button>
-              ))}
-            </Stack>
-          )}
-        </div>
-      )}
-
-      {!streaming && !thinking && (
-        <Cluster space="0" className="velu-chatbot__msg-actions">
-          {['copy', 'thumbs-up', 'thumbs-down'].map((ic) => {
-            const active =
-              (ic === 'thumbs-up' && vote === 'up') ||
-              (ic === 'thumbs-down' && vote === 'down');
-            const label = ic === 'copy' && copied ? 'check' : ic;
-            return (
-              <button
-                key={ic}
-                type="button"
-                className={`velu-chatbot__msg-action${active ? ' is-active' : ''}`}
-                aria-label={ic}
-                aria-pressed={ic === 'copy' ? undefined : active}
-                onClick={() => onAction(ic)}
-              >
-                {resolveIcon(label, { size: '1em' })}
-              </button>
-            );
-          })}
-        </Cluster>
-      )}
-    </div>
-  );
-}
-
-/* ── Composer ───────────────────────────────────────────────────────── */
-function Composer({ value, onChange, onSubmit, disabled }) {
-  const taRef = useRef(null);
-  useEffect(() => {
-    const ta = taRef.current;
-    if (!ta) return;
-    ta.style.height = 'auto';
-    ta.style.height = `${ta.scrollHeight}px`;
-  }, [value]);
-
-  const active = value.trim().length > 0 && !disabled;
-  const onKeyDown = (e) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault();
-      if (active) onSubmit();
-    }
-  };
-
-  return (
-    <div className="velu-chatbot__composer">
-      <div className="velu-chatbot__input-wrap">
-        <textarea
-          ref={taRef}
-          className="velu-chatbot__input"
-          placeholder="Ask anything about the docs…"
-          rows={1}
-          value={value}
-          onChange={(e) => onChange(e.target.value)}
-          onKeyDown={onKeyDown}
-        />
-        <button
-          type="button"
-          className={`velu-chatbot__send${active ? ' is-active' : ''}`}
-          onClick={onSubmit}
-          disabled={!active}
-          aria-label="Send"
-        >
-          {resolveIcon('arrow-up', { size: '1em' })}
-        </button>
-      </div>
-      <div className="velu-chatbot__foot">
-        <kbd>Enter</kbd> to send · <kbd>⇧ Enter</kbd> for newline
-      </div>
-    </div>
-  );
-}
-
-/* ── Panel ──────────────────────────────────────────────────────────── */
-export default function Chatbot({
-  open = false,
-  seedQuestion,
-  onClose,
-  ask,
-  onFeedback,
-  onNavigate,
-  listHistory,
-  loadConversation,
-  suggestions,
-  className = '',
-  ...rest
-}) {
-  const [messages, setMessages] = useState([]);
-  const [input, setInput] = useState('');
-  const [historyOpen, setHistoryOpen] = useState(false);
-  const [history, setHistory] = useState([]);
-  const [historyLoading, setHistoryLoading] = useState(false);
-  const bodyRef = useRef(null);
-  const streamingRef = useRef(false);
-  const lastSeedRef = useRef(undefined);
-  // Real-backend session: conversation id threads turns; the controller lets
-  // a new-chat / close / unmount abort an in-flight stream.
-  const convoRef = useRef(undefined);
-  const abortRef = useRef(null);
-
-  useEffect(() => {
-    const el = bodyRef.current;
-    if (el) el.scrollTop = el.scrollHeight;
-  }, [messages]);
-
-  // Merge a patch into the last (assistant) message.
-  const patchLast = useCallback((patch) => {
-    setMessages((prev) => {
-      if (!prev.length) return prev;
-      const out = prev.slice();
-      out[out.length - 1] = { ...out[out.length - 1], ...patch };
-      return out;
-    });
-  }, []);
-
-  // Stop whatever is in flight — a canned setTimeout chain ({ timer }) or a
-  // real fetch stream (an AbortController). Safe to call any time.
-  const cancelInFlight = useCallback(() => {
-    const a = abortRef.current;
-    if (a) {
-      if (a.timer) clearTimeout(a.timer);
-      if (typeof a.abort === 'function') a.abort();
-    }
-    abortRef.current = null;
-    streamingRef.current = false;
-  }, []);
-
-  // Real history: fetch the visitor's conversations when the panel opens.
-  // Without a backend (dev preview) the canned demo entries show instead.
-  useEffect(() => {
-    if (!historyOpen) return;
-    if (!listHistory) {
-      setHistory(HISTORY.map((h) => ({ ...h, demo: true })));
-      return;
-    }
-    let stale = false;
-    setHistoryLoading(true);
-    listHistory()
-      .then((items) => {
-        if (stale) return;
-        setHistory(items.map((c) => ({
-          id: c.conversationId,
-          title: c.title,
-          when: whenLabel(c.updatedAt),
-          conversation: c,
-        })));
-      })
-      .catch(() => { if (!stale) setHistory([]); })
-      .finally(() => { if (!stale) setHistoryLoading(false); });
-    return () => { stale = true; };
-  }, [historyOpen, listHistory]);
-
-  // Resume a past conversation: load its turns into the panel and thread the
-  // conversation id so follow-up asks continue it.
-  const openConversation = useCallback(
-    async (item) => {
-      setHistoryOpen(false);
-      if (!item.conversation || !loadConversation) return; // demo entry
-      cancelInFlight();
-      try {
-        const { conversationId, messages: msgs } = await loadConversation(item.conversation);
-        convoRef.current = conversationId;
-        setMessages(msgs.map((m) =>
-          m.role === 'user'
-            ? { role: 'user', text: m.content }
-            : {
-                role: 'ai',
-                tokens: textToTokens(m.content),
-                sources: m.citations || [],
-                followups: [],
-                streaming: false,
-                messageId: m.messageId,
-              },
-        ));
-      } catch {
-        /* keep the current chat if the load fails */
-      }
-    },
-    [loadConversation, cancelInFlight],
-  );
-
-  const send = useCallback(
-    async (text) => {
-      const prompt = String(text ?? '').trim();
-      if (!prompt || streamingRef.current) return;
-      setInput('');
-
-      // ── No backend wired → canned, fake-streamed demo answer ──────────
-      if (!ask) {
-        const answer = buildAnswer();
-        const fullTokens = tokenizeAnswer(answer);
-        setMessages((prev) => [
-          ...prev,
-          { role: 'user', text: prompt },
-          {
-            role: 'ai',
-            tokens: [],
-            sources: answer.sources,
-            followups: answer.followups,
-            streaming: true,
-          },
-        ]);
-        streamingRef.current = true;
-        let i = 0;
-        const step = () => {
-          i = Math.min(fullTokens.length, i + 1);
-          patchLast({
-            tokens: fullTokens.slice(0, i),
-            streaming: i < fullTokens.length,
-          });
-          if (i < fullTokens.length) {
-            abortRef.current = { timer: setTimeout(step, 28) };
-          } else {
-            streamingRef.current = false;
-            abortRef.current = null;
-          }
-        };
-        abortRef.current = { timer: setTimeout(step, 1400) }; // "thinking" pause
-        return;
-      }
-
-      // ── Real backend → stream deltas + citations from `ask` ───────────
-      setMessages((prev) => [
-        ...prev,
-        { role: 'user', text: prompt },
-        { role: 'ai', tokens: [], sources: [], followups: [], streaming: true },
-      ]);
-      streamingRef.current = true;
-      const controller =
-        typeof AbortController !== 'undefined' ? new AbortController() : null;
-      abortRef.current = controller;
-
-      let acc = '';
-      let sources = [];
-      let messageId;
-      try {
-        for await (const ev of ask(prompt, {
-          conversationId: convoRef.current,
-          signal: controller?.signal,
-        })) {
-          if (ev.conversationId) convoRef.current = ev.conversationId;
-          if (ev.messageId) messageId = ev.messageId;
-          if (ev.delta) acc += ev.delta;
-          if (ev.citations) {
-            sources = ev.citations.map((c, idx) => ({
-              num: c.num ?? idx + 1,
-              title: c.title,
-              path: c.path ?? c.route_path,
-              url: c.url,
-            }));
-          }
-          patchLast({ tokens: textToTokens(acc), sources, streaming: true, messageId });
-        }
-        patchLast({ tokens: textToTokens(acc), sources, streaming: false, messageId });
-      } catch (err) {
-        if (controller?.signal?.aborted) {
-          patchLast({ streaming: false });
-        } else {
-          patchLast({
-            tokens: textToTokens(
-              acc || 'Sorry — I couldn’t reach the assistant. Please try again.'
-            ),
-            streaming: false,
-            error: true,
-          });
-        }
-      } finally {
-        streamingRef.current = false;
-        abortRef.current = null;
-      }
-    },
-    [ask, patchLast]
-  );
-
-  // Abort any in-flight stream when the panel unmounts.
-  useEffect(() => () => cancelInFlight(), [cancelInFlight]);
-
-  // A new seedQuestion (from the page's AskBar) sends the first message.
-  useEffect(() => {
-    if (open && seedQuestion && seedQuestion !== lastSeedRef.current) {
-      lastSeedRef.current = seedQuestion;
-      send(seedQuestion);
-    }
-  }, [open, seedQuestion, send]);
-
-  const newChat = () => {
-    cancelInFlight();
-    convoRef.current = undefined; // fresh conversation thread
-    setMessages([]);
-    setInput('');
-    setHistoryOpen(false);
-  };
-
-  // Drag-to-dismiss (mobile bottom-sheet only). Pointer events are
-  // attached to the drag-handle element below; the handle's pointer
-  // capture keeps the events flowing even if the finger slides off
-  // the handle into the body. While dragging we apply an inline
-  // `transform: translateY(...)` to the panel, overriding the CSS-
-  // controlled transform. On release, if the drag distance exceeded
-  // the threshold we call onClose() and the panel slides the rest of
-  // the way down via the CSS transition; otherwise we drop the
-  // inline transform and the panel snaps back via the same
-  // transition.
-  const dragRef = useRef({ active: false, startY: 0, currentY: 0 });
-  const [dragOffset, setDragOffset] = useState(0);
-  // Drag-to-dismiss is active wherever the chatbot is rendered as a
-  // bottom sheet — same threshold as the @container query in
-  // chatbot.css (< 1024px covers both narrow / tablet and mobile).
-  const isBottomSheet = () =>
-    typeof window !== 'undefined' &&
-    window.matchMedia('(max-width: 1024px)').matches;
-  const onDragStart = (e) => {
-    if (!isBottomSheet()) return;
-    dragRef.current = { active: true, startY: e.clientY, currentY: 0 };
-    e.currentTarget.setPointerCapture?.(e.pointerId);
-  };
-  const onDragMove = (e) => {
-    if (!dragRef.current.active) return;
-    const delta = Math.max(0, e.clientY - dragRef.current.startY);
-    dragRef.current.currentY = delta;
-    setDragOffset(delta);
-  };
-  const onDragEnd = () => {
-    if (!dragRef.current.active) return;
-    dragRef.current.active = false;
-    const shouldClose = dragRef.current.currentY > 80;
-    setDragOffset(0);
-    if (shouldClose) onClose?.();
-  };
-  // Reset any residual drag offset whenever the panel closes from
-  // outside (scrim click, X button, etc.) so a re-open starts clean.
-  useEffect(() => {
-    if (!open) setDragOffset(0);
-  }, [open]);
-
-  const cls = `velu-chatbot${open ? ' velu-chatbot--open' : ''} ${className}`.trim();
-  const dragStyle =
-    dragOffset > 0
-      ? { transform: `translateY(${dragOffset}px)`, transition: 'none' }
-      : undefined;
-
-  return (
-    <aside
-      className={cls}
-      aria-hidden={!open}
-      aria-label="Ask AI"
-      style={dragStyle}
-      {...rest}
-    >
-      {/* Drag handle — mobile only (CSS in chatbot.css). The pill
-          visual + the touch-capturing strip across the top of the
-          sheet. Pointer events here drive the drag-to-dismiss
-          gesture above. */}
-      <div
-        className="velu-chatbot__drag-handle"
-        onPointerDown={onDragStart}
-        onPointerMove={onDragMove}
-        onPointerUp={onDragEnd}
-        onPointerCancel={onDragEnd}
-        aria-hidden="true"
-      />
-      <ChatHeader
-        onClose={onClose}
-        onNew={newChat}
-        onHistory={() => setHistoryOpen((o) => !o)}
-        historyOpen={historyOpen}
-      />
-
-      {historyOpen && (
-        <HistoryPanel
-          items={history}
-          loading={historyLoading}
-          onClose={() => setHistoryOpen(false)}
-          onPick={openConversation}
-        />
-      )}
-
-      <div className="velu-chatbot__body" ref={bodyRef}>
-        {messages.length === 0 ? (
-          <Welcome onPick={(t) => send(t)} suggestions={suggestions} />
-        ) : (
-          <Stack space="var(--s1)">
-            {messages.map((m, i) =>
-              m.role === 'user' ? (
-                <UserMsg key={i} text={m.text} />
-              ) : (
-                <AiMsg
-                  key={i}
-                  tokens={m.tokens}
-                  sources={m.sources}
-                  followups={m.followups}
-                  streaming={m.streaming}
-                  messageId={m.messageId}
-                  onFeedback={onFeedback}
-                  onNavigate={onNavigate}
-                  onFollowup={(f) => send(f)}
-                />
-              ),
-            )}
-          </Stack>
-        )}
-      </div>
-
-      <Composer
-        value={input}
-        onChange={setInput}
-        onSubmit={() => send(input)}
-        disabled={streamingRef.current}
-      />
-    </aside>
-  );
-}
+import React, { useState, useRef, useEffect, useCallback } from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import Stack from '../primitives/Stack.jsx';
+import Cluster from '../primitives/Cluster.jsx';
+
+/**
+ * Chatbot — the Velu "Ask AI" panel. A right-side slide-out: header +
+ * scrolling message body + composer. Ported from the Claude-Design
+ * "Velu Chatbot" handoff (rich variant), retokenized onto velu-ui's
+ * scale so it themes for free via [data-theme].
+ *
+ *   <Chatbot
+ *     open={chatOpen}
+ *     seedQuestion={question}      // first message — sent on open
+ *     onClose={() => setChatOpen(false)}
+ *     ask={askDocs}                // OPTIONAL — real backend (see below)
+ *     onFeedback={(id, v) => …}    // OPTIONAL — 👍/👎 for a message
+ *   />
+ *
+ * Slide: the panel is fixed to the inline-end edge; `open` toggles a
+ * `translateX` between fully off-screen and 0. Width is the
+ * `--vchat-width` variable (default 24rem ≈ the design's 384px).
+ *
+ * Backend seam (mirrors Search.jsx's injectable `search` prop):
+ *   ask(prompt, { conversationId, signal }) → AsyncIterable<AskEvent>
+ *   AskEvent = {
+ *     delta?: string,            // text chunk to append (streamed)
+ *     citations?: Source[],      // [{ num, title, path, url }] — replaces sources
+ *     messageId?: string,        // assistant message id (for feedback)
+ *     conversationId?: string,   // threaded across turns
+ *   }
+ * When `ask` is omitted the panel falls back to a canned, fake-streamed
+ * demo answer (so dev preview / offline still shows the experience).
+ */
+
+/* ── Brand mark — the Velu double-hook logo ─────────────────────────── */
+// `size` is the glyph height; width derives from the 32:24 viewBox.
+function VeluMark({ size = 'var(--icon-size-lg)' }) {
+  return (
+    <svg
+      className="velu-chatbot__mark"
+      viewBox="0 0 32 24"
+      fill="currentColor"
+      aria-hidden="true"
+      style={{ width: `calc(${size} * (32 / 24))`, height: size }}
+    >
+      <path d="M 29.656 14.153 C 29.574 14.562 29.351 14.929 29.025 15.193 C 28.699 15.457 28.291 15.601 27.869 15.601 L 21.37 15.601 C 20.534 15.601 19.805 16.163 19.603 16.964 L 18.167 22.637 C 18.068 23.026 17.841 23.372 17.521 23.619 C 17.2 23.866 16.805 24 16.399 24 L 10.438 24 C 10.161 24 9.888 23.938 9.639 23.818 C 9.39 23.698 9.172 23.524 9.001 23.308 C 8.831 23.092 8.712 22.841 8.655 22.574 C 8.598 22.306 8.603 22.029 8.67 21.764 L 10.189 15.764 C 10.287 15.374 10.515 15.029 10.835 14.782 C 11.155 14.535 11.55 14.401 11.956 14.4 L 18.393 14.4 C 19.262 14.4 20.01 13.795 20.18 12.953 L 22.388 2.048 C 22.471 1.639 22.694 1.272 23.019 1.008 C 23.345 0.744 23.754 0.6 24.175 0.6 L 30.177 0.6 C 30.447 0.6 30.713 0.659 30.957 0.773 C 31.201 0.886 31.416 1.052 31.587 1.258 C 31.758 1.464 31.881 1.705 31.946 1.964 C 32.011 2.222 32.017 2.492 31.964 2.753 L 29.656 14.153 Z M 9.611 13.554 C 9.528 13.962 9.305 14.329 8.979 14.593 C 8.653 14.857 8.245 15.001 7.824 15.001 L 1.823 15.001 C 1.553 15.001 1.287 14.942 1.043 14.828 C 0.799 14.714 0.584 14.548 0.413 14.342 C 0.242 14.136 0.119 13.895 0.054 13.637 C -0.011 13.378 -0.017 13.109 0.036 12.848 L 2.344 1.447 C 2.426 1.039 2.649 0.672 2.975 0.408 C 3.301 0.144 3.709 0 4.131 0 L 10.132 0 C 10.402 0 10.668 0.059 10.912 0.173 C 11.155 0.287 11.371 0.453 11.541 0.659 C 11.712 0.865 11.835 1.106 11.9 1.364 C 11.965 1.623 11.972 1.892 11.919 2.153 L 9.611 13.553 L 9.611 13.554 Z" />
+    </svg>
+  );
+}
+
+/* ── "Thinking" loader — 3x3 grid of squares, opacity wave sweeps the
+   anti-diagonal so it ripples top-left → bottom-right. ─────────────── */
+function BlocksWave() {
+  const cells = [
+    [1, 1, 0], [8.33, 1, 1], [15.66, 1, 2],
+    [1, 8.33, 1], [8.33, 8.33, 2], [15.66, 8.33, 3],
+    [1, 15.66, 2], [8.33, 15.66, 3], [15.66, 15.66, 4],
+  ];
+  return (
+    <svg className="velu-chatbot__wave" viewBox="0 0 24 24" aria-hidden="true">
+      {cells.map(([x, y, cell], i) => (
+        <rect key={i} x={x} y={y} width="7.33" height="7.33" data-cell={cell} />
+      ))}
+    </svg>
+  );
+}
+
+/* ── Demo data ──────────────────────────────────────────────────────── */
+const SUGGESTIONS = [
+  { label: 'How do I set up GitHub sync?', icon: 'github' },
+  { label: 'Customize the look of my docs site', icon: 'book' },
+  { label: 'Configure AI search ranking', icon: 'sparkles' },
+  { label: 'Quickstart in under five minutes', icon: 'rocket' },
+];
+
+const HISTORY = [
+  { id: 'h1', title: 'Setting up GitHub sync', when: 'Today, 10:24' },
+  { id: 'h2', title: 'Custom theme tokens & dark mode', when: 'Today, 09:11' },
+  { id: 'h3', title: 'Configure AI search ranking', when: 'Yesterday' },
+  { id: 'h4', title: 'Embed a Mermaid diagram in MDX', when: 'Yesterday' },
+  { id: 'h5', title: 'Why are my callouts missing icons?', when: 'Apr 28' },
+  { id: 'h6', title: 'Quickstart — minimum site config', when: 'Apr 27' },
+];
+
+const SOURCES = [
+  { num: 1, title: 'GitHub & GitLab Sync', path: 'docs/integrations/github-sync.md' },
+  { num: 2, title: 'Site Settings — Repositories', path: 'docs/your-docs-site/site-settings.md' },
+  { num: 3, title: 'AI-native Documentation', path: 'docs/get-started/ai-native.md' },
+];
+
+/* Canned answer — segments interleave text, inline `code`, and citation
+   markers. The same answer is returned for any prompt (demo). */
+function buildAnswer() {
+  return {
+    segments: [
+      { t: 'Velu syncs documentation directly with GitHub and GitLab — every push to a connected repository updates the live docs site within seconds.' },
+      { cite: 1 },
+      { t: ' To set it up:\n\n1. Open ' },
+      { code: 'Site Settings → Repositories' },
+      { t: ' and click ' },
+      { code: 'Connect repository' },
+      { t: '.\n2. Authorize the Velu app on the org that owns the repo.\n3. Pick a branch (default ' },
+      { code: 'main' },
+      { t: ') and a docs root path.' },
+      { cite: 2 },
+      { t: '\n\nVelu watches changes to ' },
+      { code: '.md' },
+      { t: ' and ' },
+      { code: '.mdx' },
+      { t: ' files and re-indexes the site automatically.' },
+      { cite: 3 },
+    ],
+    sources: SOURCES,
+    followups: [
+      'How do I preview pull-request changes?',
+      'Can I sync from a monorepo subdirectory?',
+      'What about private repositories?',
+    ],
+  };
+}
+
+/* Real-backend path: turn the accumulated answer TEXT into the same token
+   shape `renderStream` consumes. The assistant streams plain text with inline
+   `code` spans and bracketed citation markers ([1], [2]); split those out so
+   they render as <code> and citation chips, exactly like the canned path. */
+function textToTokens(text) {
+  const tokens = [];
+  const re = /(`[^`]*`|\[\d+\])/g;
+  let last = 0;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    if (m.index > last) tokens.push({ kind: 't', v: text.slice(last, m.index) });
+    const tok = m[0];
+    if (tok[0] === '`') tokens.push({ kind: 'code', v: tok.slice(1, -1) });
+    else tokens.push({ kind: 'cite', n: Number(tok.slice(1, -1)) });
+    last = re.lastIndex;
+  }
+  if (last < text.length) tokens.push({ kind: 't', v: text.slice(last) });
+  return tokens;
+}
+
+/* Plain-text of an answer (for the Copy action). */
+function tokensToPlain(tokens) {
+  return tokens
+    .map((tk) => (tk.kind === 'cite' ? `[${tk.n}]` : tk.v))
+    .join('')
+    .trim();
+}
+
+/* Flatten an answer into a stream of small tokens for incremental render. */
+function tokenizeAnswer(answer) {
+  const tokens = [];
+  for (const seg of answer.segments) {
+    if (seg.cite != null) { tokens.push({ kind: 'cite', n: seg.cite }); continue; }
+    if (seg.code != null) { tokens.push({ kind: 'code', v: seg.code }); continue; }
+    const parts = seg.t.match(/\S+\s*|\s+/g) || [seg.t];
+    for (const p of parts) tokens.push({ kind: 't', v: p });
+  }
+  return tokens;
+}
+
+/* A citation's in-site target. Real backend sources carry a `url` (and `path`
+   is a route like "/essentials/code"); the demo's `path` is a fake file path,
+   so those stay inert. */
+function sourceHref(s) {
+  if (s?.url) return s.url;
+  if (s?.path && s.path.startsWith('/')) return s.path;
+  return null;
+}
+
+/* A readable label for a source: the section heading if present, else a title
+   derived from the route (e.g. "/essentials/settings" → "Settings"). */
+function citeTitle(s) {
+  if (s?.title) return s.title;
+  const path = (s?.path || '').replace(/[#?].*$/, '');
+  const seg = path.split('/').filter(Boolean).pop();
+  if (!seg) return 'Documentation';
+  return seg.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/* Source click: SPA-navigate same-origin targets via onNavigate (keeps the chat
+   panel open + scrolls to the heading); otherwise let the <a href> navigate. */
+function onSourceClick(e, s, onNavigate) {
+  const href = sourceHref(s);
+  if (!href) { e.preventDefault(); return; }
+  if (!onNavigate) return; // no SPA hook → let the browser follow the href
+  try {
+    const u = new URL(href, window.location.origin);
+    if (u.origin === window.location.origin) {
+      e.preventDefault();
+      onNavigate(u.pathname + u.search + u.hash);
+    }
+  } catch { /* malformed — fall back to href */ }
+}
+
+/* Render partial tokens as paragraphs (split on \n\n, single \n → <br>). */
+function renderStream(tokens, sources, onNavigate) {
+  const paragraphs = [[]];
+  for (const tk of tokens) {
+    if (tk.kind === 't' && tk.v.includes('\n\n')) {
+      const split = tk.v.split('\n\n');
+      paragraphs[paragraphs.length - 1].push({ kind: 't', v: split[0] });
+      for (let i = 1; i < split.length; i++) {
+        paragraphs.push([]);
+        if (split[i]) paragraphs[paragraphs.length - 1].push({ kind: 't', v: split[i] });
+      }
+    } else {
+      paragraphs[paragraphs.length - 1].push(tk);
+    }
+  }
+  return paragraphs.map((para, pi) => (
+    <p key={pi}>
+      {para.map((tk, i) => {
+        if (tk.kind === 'cite') {
+          const src = sources?.find((s) => s.num === tk.n);
+          return (
+            <a
+              key={i}
+              className="velu-chatbot__cite"
+              href={sourceHref(src) || '#'}
+              onClick={(e) => onSourceClick(e, src, onNavigate)}
+              title={citeTitle(src)}
+            >
+              {tk.n}
+            </a>
+          );
+        }
+        if (tk.kind === 'code') return <code key={i}>{tk.v}</code>;
+        const lines = tk.v.split('\n');
+        return lines.map((line, li) => (
+          <React.Fragment key={`${i}-${li}`}>
+            {li > 0 && <br />}
+            {line}
+          </React.Fragment>
+        ));
+      })}
+    </p>
+  ));
+}
+
+/* ── Header ─────────────────────────────────────────────────────────── */
+function ChatHeader({ onClose, onNew, onHistory, historyOpen }) {
+  return (
+    <Cluster
+      space="var(--s-2)"
+      justify="space-between"
+      align="center"
+      className="velu-chatbot__header"
+    >
+      <Cluster space="var(--s-2)" align="center">
+        <VeluMark />
+        <span className="velu-chatbot__brand">
+          <span className="velu-chatbot__brand-name">Velu</span>
+          <span className="velu-chatbot__brand-sep">/</span>
+          <span className="velu-chatbot__brand-title">Ask AI</span>
+        </span>
+      </Cluster>
+      <Cluster space="var(--s-5)" align="center">
+        <button
+          type="button"
+          className={`velu-chatbot__iconbtn${historyOpen ? ' is-active' : ''}`}
+          aria-label="History"
+          onClick={onHistory}
+        >
+          {resolveIcon('history', { size: '1em' })}
+        </button>
+        <button
+          type="button"
+          className="velu-chatbot__iconbtn"
+          aria-label="New chat"
+          onClick={onNew}
+        >
+          {resolveIcon('plus', { size: '1em' })}
+        </button>
+        <button
+          type="button"
+          className="velu-chatbot__iconbtn"
+          aria-label="Close"
+          onClick={onClose}
+        >
+          {resolveIcon('x', { size: '1em' })}
+        </button>
+      </Cluster>
+    </Cluster>
+  );
+}
+
+/* ── History overlay ────────────────────────────────────────────────── */
+
+/* "Today, 10:24" / "Yesterday" / "Apr 28" for a conversation timestamp. */
+function whenLabel(iso) {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  const startOfDay = (x) => new Date(x.getFullYear(), x.getMonth(), x.getDate());
+  const days = Math.round((startOfDay(new Date()) - startOfDay(d)) / 86400000);
+  if (days <= 0) {
+    return `Today, ${d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}`;
+  }
+  if (days === 1) return 'Yesterday';
+  return d.toLocaleDateString([], { month: 'short', day: 'numeric' });
+}
+
+function HistoryPanel({ items, loading, onPick, onClose }) {
+  return (
+    <div className="velu-chatbot__history">
+      <Cluster
+        space="var(--s-2)"
+        justify="space-between"
+        align="center"
+        className="velu-chatbot__history-head"
+      >
+        <span className="velu-chatbot__eyebrow">Recent chats</span>
+        <button
+          type="button"
+          className="velu-chatbot__iconbtn"
+          aria-label="Close history"
+          onClick={onClose}
+        >
+          {resolveIcon('x', { size: '1em' })}
+        </button>
+      </Cluster>
+      <Stack as="div" space="var(--s-5)" className="velu-chatbot__history-list">
+        {loading ? (
+          <span className="velu-chatbot__history-empty">Loading…</span>
+        ) : items.length === 0 ? (
+          <span className="velu-chatbot__history-empty">No conversations yet.</span>
+        ) : (
+          items.map((h) => (
+            <button
+              key={h.id}
+              type="button"
+              className="velu-chatbot__history-item"
+              onClick={() => onPick(h)}
+            >
+              <span className="velu-chatbot__history-item-title">{h.title}</span>
+              <span className="velu-chatbot__history-item-when">{h.when}</span>
+            </button>
+          ))
+        )}
+      </Stack>
+    </div>
+  );
+}
+
+/* ── Welcome / empty state ──────────────────────────────────────────── */
+function Welcome({ onPick, suggestions }) {
+  // Site-specific starter questions (velu.json assistant.suggestions, or
+  // publish-time generated); the canned demo list is the dev-preview fallback.
+  const items = suggestions?.length
+    ? suggestions.map((label) => ({ label, icon: 'sparkles' }))
+    : SUGGESTIONS;
+  return (
+    <Stack space="var(--s0)" className="velu-chatbot__welcome">
+      <p className="velu-chatbot__welcome-hi">Ask anything about the docs.</p>
+      <span className="velu-chatbot__eyebrow">Suggested</span>
+      <Stack space="var(--s-4)">
+        {items.map((s, i) => (
+          <button
+            key={i}
+            type="button"
+            className="velu-chatbot__suggest"
+            onClick={() => onPick(s.label)}
+          >
+            <Cluster space="var(--s-2)" align="center">
+              {resolveIcon(s.icon, { size: '1em' })}
+              <span>{s.label}</span>
+            </Cluster>
+            {resolveIcon('arrow-right', { size: '1em' })}
+          </button>
+        ))}
+      </Stack>
+    </Stack>
+  );
+}
+
+/* ── Messages ───────────────────────────────────────────────────────── */
+function UserMsg({ text }) {
+  return (
+    <div className="velu-chatbot__msg velu-chatbot__msg--user">
+      <div className="velu-chatbot__bubble">{text}</div>
+    </div>
+  );
+}
+
+function AiMsg({
+  tokens,
+  sources,
+  followups,
+  streaming,
+  onFollowup,
+  messageId,
+  onFeedback,
+  onNavigate,
+}) {
+  const thinking = tokens.length === 0;
+  const [vote, setVote] = useState(null); // 'up' | 'down' | null
+  const [copied, setCopied] = useState(false);
+
+  const onAction = (ic) => {
+    if (ic === 'copy') {
+      try {
+        navigator.clipboard?.writeText(tokensToPlain(tokens));
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1400);
+      } catch {
+        /* clipboard blocked — no-op */
+      }
+      return;
+    }
+    if (ic === 'thumbs-up' || ic === 'thumbs-down') {
+      const v = ic === 'thumbs-up' ? 'up' : 'down';
+      const next = vote === v ? null : v; // toggle off if re-clicked
+      setVote(next);
+      onFeedback?.(messageId, next); // null = retract
+    }
+  };
+  return (
+    <div className="velu-chatbot__msg velu-chatbot__msg--ai">
+      <Cluster
+        space="var(--s-3)"
+        align="center"
+        className={`velu-chatbot__role${thinking ? ' is-thinking' : ''}`}
+      >
+        {thinking ? <BlocksWave /> : resolveIcon('sparkles', { size: '1em' })}
+        <span>{thinking ? 'Velu is thinking' : 'Velu'}</span>
+      </Cluster>
+
+      {!thinking && (
+        <div className="velu-chatbot__answer">
+          {renderStream(tokens, sources, onNavigate)}
+          {streaming && <span className="velu-chatbot__caret" />}
+
+          {!streaming && sources?.length > 0 && (
+            <Stack space="var(--s-4)" className="velu-chatbot__sources">
+              <span className="velu-chatbot__eyebrow">Sources</span>
+              {sources.map((s) => (
+                <a
+                  key={s.num}
+                  className="velu-chatbot__source"
+                  href={sourceHref(s) || '#'}
+                  onClick={(e) => onSourceClick(e, s, onNavigate)}
+                >
+                  <span className="velu-chatbot__source-num">{s.num}</span>
+                  <span className="velu-chatbot__source-meta">
+                    <span className="velu-chatbot__source-title">{citeTitle(s)}</span>
+                    <span className="velu-chatbot__source-path">{s.path}</span>
+                  </span>
+                </a>
+              ))}
+            </Stack>
+          )}
+
+          {!streaming && followups?.length > 0 && (
+            <Stack space="var(--s-4)" className="velu-chatbot__followups">
+              <span className="velu-chatbot__eyebrow">Follow up</span>
+              {followups.map((f, i) => (
+                <button
+                  key={i}
+                  type="button"
+                  className="velu-chatbot__followup"
+                  onClick={() => onFollowup(f)}
+                >
+                  <span>{f}</span>
+                  {resolveIcon('arrow-right', { size: '1em' })}
+                </button>
+              ))}
+            </Stack>
+          )}
+        </div>
+      )}
+
+      {!streaming && !thinking && (
+        <Cluster space="0" className="velu-chatbot__msg-actions">
+          {['copy', 'thumbs-up', 'thumbs-down'].map((ic) => {
+            const active =
+              (ic === 'thumbs-up' && vote === 'up') ||
+              (ic === 'thumbs-down' && vote === 'down');
+            const label = ic === 'copy' && copied ? 'check' : ic;
+            return (
+              <button
+                key={ic}
+                type="button"
+                className={`velu-chatbot__msg-action${active ? ' is-active' : ''}`}
+                aria-label={ic}
+                aria-pressed={ic === 'copy' ? undefined : active}
+                onClick={() => onAction(ic)}
+              >
+                {resolveIcon(label, { size: '1em' })}
+              </button>
+            );
+          })}
+        </Cluster>
+      )}
+    </div>
+  );
+}
+
+/* ── Composer ───────────────────────────────────────────────────────── */
+function Composer({ value, onChange, onSubmit, disabled }) {
+  const taRef = useRef(null);
+  useEffect(() => {
+    const ta = taRef.current;
+    if (!ta) return;
+    ta.style.height = 'auto';
+    ta.style.height = `${ta.scrollHeight}px`;
+  }, [value]);
+
+  const active = value.trim().length > 0 && !disabled;
+  const onKeyDown = (e) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      if (active) onSubmit();
+    }
+  };
+
+  return (
+    <div className="velu-chatbot__composer">
+      <div className="velu-chatbot__input-wrap">
+        <textarea
+          ref={taRef}
+          className="velu-chatbot__input"
+          placeholder="Ask anything about the docs…"
+          rows={1}
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          onKeyDown={onKeyDown}
+        />
+        <button
+          type="button"
+          className={`velu-chatbot__send${active ? ' is-active' : ''}`}
+          onClick={onSubmit}
+          disabled={!active}
+          aria-label="Send"
+        >
+          {resolveIcon('arrow-up', { size: '1em' })}
+        </button>
+      </div>
+      <div className="velu-chatbot__foot">
+        <kbd>Enter</kbd> to send · <kbd>⇧ Enter</kbd> for newline
+      </div>
+    </div>
+  );
+}
+
+/* ── Panel ──────────────────────────────────────────────────────────── */
+export default function Chatbot({
+  open = false,
+  seedQuestion,
+  onClose,
+  ask,
+  onFeedback,
+  onNavigate,
+  listHistory,
+  loadConversation,
+  suggestions,
+  className = '',
+  ...rest
+}) {
+  const [messages, setMessages] = useState([]);
+  const [input, setInput] = useState('');
+  const [historyOpen, setHistoryOpen] = useState(false);
+  const [history, setHistory] = useState([]);
+  const [historyLoading, setHistoryLoading] = useState(false);
+  const bodyRef = useRef(null);
+  const streamingRef = useRef(false);
+  const lastSeedRef = useRef(undefined);
+  // Real-backend session: conversation id threads turns; the controller lets
+  // a new-chat / close / unmount abort an in-flight stream.
+  const convoRef = useRef(undefined);
+  const abortRef = useRef(null);
+
+  useEffect(() => {
+    const el = bodyRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [messages]);
+
+  // Merge a patch into the last (assistant) message.
+  const patchLast = useCallback((patch) => {
+    setMessages((prev) => {
+      if (!prev.length) return prev;
+      const out = prev.slice();
+      out[out.length - 1] = { ...out[out.length - 1], ...patch };
+      return out;
+    });
+  }, []);
+
+  // Stop whatever is in flight — a canned setTimeout chain ({ timer }) or a
+  // real fetch stream (an AbortController). Safe to call any time.
+  const cancelInFlight = useCallback(() => {
+    const a = abortRef.current;
+    if (a) {
+      if (a.timer) clearTimeout(a.timer);
+      if (typeof a.abort === 'function') a.abort();
+    }
+    abortRef.current = null;
+    streamingRef.current = false;
+  }, []);
+
+  // Real history: fetch the visitor's conversations when the panel opens.
+  // Without a backend (dev preview) the canned demo entries show instead.
+  useEffect(() => {
+    if (!historyOpen) return;
+    if (!listHistory) {
+      setHistory(HISTORY.map((h) => ({ ...h, demo: true })));
+      return;
+    }
+    let stale = false;
+    setHistoryLoading(true);
+    listHistory()
+      .then((items) => {
+        if (stale) return;
+        setHistory(items.map((c) => ({
+          id: c.conversationId,
+          title: c.title,
+          when: whenLabel(c.updatedAt),
+          conversation: c,
+        })));
+      })
+      .catch(() => { if (!stale) setHistory([]); })
+      .finally(() => { if (!stale) setHistoryLoading(false); });
+    return () => { stale = true; };
+  }, [historyOpen, listHistory]);
+
+  // Resume a past conversation: load its turns into the panel and thread the
+  // conversation id so follow-up asks continue it.
+  const openConversation = useCallback(
+    async (item) => {
+      setHistoryOpen(false);
+      if (!item.conversation || !loadConversation) return; // demo entry
+      cancelInFlight();
+      try {
+        const { conversationId, messages: msgs } = await loadConversation(item.conversation);
+        convoRef.current = conversationId;
+        setMessages(msgs.map((m) =>
+          m.role === 'user'
+            ? { role: 'user', text: m.content }
+            : {
+                role: 'ai',
+                tokens: textToTokens(m.content),
+                sources: m.citations || [],
+                followups: [],
+                streaming: false,
+                messageId: m.messageId,
+              },
+        ));
+      } catch {
+        /* keep the current chat if the load fails */
+      }
+    },
+    [loadConversation, cancelInFlight],
+  );
+
+  const send = useCallback(
+    async (text) => {
+      const prompt = String(text ?? '').trim();
+      if (!prompt || streamingRef.current) return;
+      setInput('');
+
+      // ── No backend wired → canned, fake-streamed demo answer ──────────
+      if (!ask) {
+        const answer = buildAnswer();
+        const fullTokens = tokenizeAnswer(answer);
+        setMessages((prev) => [
+          ...prev,
+          { role: 'user', text: prompt },
+          {
+            role: 'ai',
+            tokens: [],
+            sources: answer.sources,
+            followups: answer.followups,
+            streaming: true,
+          },
+        ]);
+        streamingRef.current = true;
+        let i = 0;
+        const step = () => {
+          i = Math.min(fullTokens.length, i + 1);
+          patchLast({
+            tokens: fullTokens.slice(0, i),
+            streaming: i < fullTokens.length,
+          });
+          if (i < fullTokens.length) {
+            abortRef.current = { timer: setTimeout(step, 28) };
+          } else {
+            streamingRef.current = false;
+            abortRef.current = null;
+          }
+        };
+        abortRef.current = { timer: setTimeout(step, 1400) }; // "thinking" pause
+        return;
+      }
+
+      // ── Real backend → stream deltas + citations from `ask` ───────────
+      setMessages((prev) => [
+        ...prev,
+        { role: 'user', text: prompt },
+        { role: 'ai', tokens: [], sources: [], followups: [], streaming: true },
+      ]);
+      streamingRef.current = true;
+      const controller =
+        typeof AbortController !== 'undefined' ? new AbortController() : null;
+      abortRef.current = controller;
+
+      let acc = '';
+      let sources = [];
+      let messageId;
+      try {
+        for await (const ev of ask(prompt, {
+          conversationId: convoRef.current,
+          signal: controller?.signal,
+        })) {
+          if (ev.conversationId) convoRef.current = ev.conversationId;
+          if (ev.messageId) messageId = ev.messageId;
+          if (ev.delta) acc += ev.delta;
+          if (ev.citations) {
+            sources = ev.citations.map((c, idx) => ({
+              num: c.num ?? idx + 1,
+              title: c.title,
+              path: c.path ?? c.route_path,
+              url: c.url,
+            }));
+          }
+          patchLast({ tokens: textToTokens(acc), sources, streaming: true, messageId });
+        }
+        patchLast({ tokens: textToTokens(acc), sources, streaming: false, messageId });
+      } catch (err) {
+        if (controller?.signal?.aborted) {
+          patchLast({ streaming: false });
+        } else {
+          patchLast({
+            tokens: textToTokens(
+              acc || 'Sorry — I couldn’t reach the assistant. Please try again.'
+            ),
+            streaming: false,
+            error: true,
+          });
+        }
+      } finally {
+        streamingRef.current = false;
+        abortRef.current = null;
+      }
+    },
+    [ask, patchLast]
+  );
+
+  // Abort any in-flight stream when the panel unmounts.
+  useEffect(() => () => cancelInFlight(), [cancelInFlight]);
+
+  // A new seedQuestion (from the page's AskBar) sends the first message.
+  useEffect(() => {
+    if (open && seedQuestion && seedQuestion !== lastSeedRef.current) {
+      lastSeedRef.current = seedQuestion;
+      send(seedQuestion);
+    }
+  }, [open, seedQuestion, send]);
+
+  const newChat = () => {
+    cancelInFlight();
+    convoRef.current = undefined; // fresh conversation thread
+    setMessages([]);
+    setInput('');
+    setHistoryOpen(false);
+  };
+
+  // Drag-to-dismiss (mobile bottom-sheet only). Pointer events are
+  // attached to the drag-handle element below; the handle's pointer
+  // capture keeps the events flowing even if the finger slides off
+  // the handle into the body. While dragging we apply an inline
+  // `transform: translateY(...)` to the panel, overriding the CSS-
+  // controlled transform. On release, if the drag distance exceeded
+  // the threshold we call onClose() and the panel slides the rest of
+  // the way down via the CSS transition; otherwise we drop the
+  // inline transform and the panel snaps back via the same
+  // transition.
+  const dragRef = useRef({ active: false, startY: 0, currentY: 0 });
+  const [dragOffset, setDragOffset] = useState(0);
+  // Drag-to-dismiss is active wherever the chatbot is rendered as a
+  // bottom sheet — same threshold as the @container query in
+  // chatbot.css (< 1024px covers both narrow / tablet and mobile).
+  const isBottomSheet = () =>
+    typeof window !== 'undefined' &&
+    window.matchMedia('(max-width: 1024px)').matches;
+  const onDragStart = (e) => {
+    if (!isBottomSheet()) return;
+    dragRef.current = { active: true, startY: e.clientY, currentY: 0 };
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+  };
+  const onDragMove = (e) => {
+    if (!dragRef.current.active) return;
+    const delta = Math.max(0, e.clientY - dragRef.current.startY);
+    dragRef.current.currentY = delta;
+    setDragOffset(delta);
+  };
+  const onDragEnd = () => {
+    if (!dragRef.current.active) return;
+    dragRef.current.active = false;
+    const shouldClose = dragRef.current.currentY > 80;
+    setDragOffset(0);
+    if (shouldClose) onClose?.();
+  };
+  // Reset any residual drag offset whenever the panel closes from
+  // outside (scrim click, X button, etc.) so a re-open starts clean.
+  useEffect(() => {
+    if (!open) setDragOffset(0);
+  }, [open]);
+
+  const cls = `velu-chatbot${open ? ' velu-chatbot--open' : ''} ${className}`.trim();
+  const dragStyle =
+    dragOffset > 0
+      ? { transform: `translateY(${dragOffset}px)`, transition: 'none' }
+      : undefined;
+
+  return (
+    <aside
+      className={cls}
+      aria-hidden={!open}
+      aria-label="Ask AI"
+      style={dragStyle}
+      {...rest}
+    >
+      {/* Drag handle — mobile only (CSS in chatbot.css). The pill
+          visual + the touch-capturing strip across the top of the
+          sheet. Pointer events here drive the drag-to-dismiss
+          gesture above. */}
+      <div
+        className="velu-chatbot__drag-handle"
+        onPointerDown={onDragStart}
+        onPointerMove={onDragMove}
+        onPointerUp={onDragEnd}
+        onPointerCancel={onDragEnd}
+        aria-hidden="true"
+      />
+      <ChatHeader
+        onClose={onClose}
+        onNew={newChat}
+        onHistory={() => setHistoryOpen((o) => !o)}
+        historyOpen={historyOpen}
+      />
+
+      {historyOpen && (
+        <HistoryPanel
+          items={history}
+          loading={historyLoading}
+          onClose={() => setHistoryOpen(false)}
+          onPick={openConversation}
+        />
+      )}
+
+      <div className="velu-chatbot__body" ref={bodyRef}>
+        {messages.length === 0 ? (
+          <Welcome onPick={(t) => send(t)} suggestions={suggestions} />
+        ) : (
+          <Stack space="var(--s1)">
+            {messages.map((m, i) =>
+              m.role === 'user' ? (
+                <UserMsg key={i} text={m.text} />
+              ) : (
+                <AiMsg
+                  key={i}
+                  tokens={m.tokens}
+                  sources={m.sources}
+                  followups={m.followups}
+                  streaming={m.streaming}
+                  messageId={m.messageId}
+                  onFeedback={onFeedback}
+                  onNavigate={onNavigate}
+                  onFollowup={(f) => send(f)}
+                />
+              ),
+            )}
+          </Stack>
+        )}
+      </div>
+
+      <Composer
+        value={input}
+        onChange={setInput}
+        onSubmit={() => send(input)}
+        disabled={streamingRef.current}
+      />
+    </aside>
+  );
+}