@clidey/dory 1.0.7 → 1.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clidey/dory",
   "private": false,
-  "version": "1.0.7",
+  "version": "1.9.0",
   "type": "module",
   "description": "A CLI tool for building and previewing documentation sites",
   "keywords": [
@@ -16,6 +16,11 @@
   },
   "files": [
     "bin/dist",
+    "dist/runtime",
+    "bin/chat-server.ts",
+    "docs",
+    "!docs/dist",
+    "!docs/dist-ssr",
     "src",
     "scripts",
     "index.html",
@@ -36,7 +41,9 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "npm run build:cli && tsc -b",
+    "build": "pnpm run build:cli && tsc -b && pnpm run build:docs && pnpm run build:runtime",
+    "build:runtime": "vite build -c vite.config.runtime.ts && cp src/embedded-runtime/runtime.html dist/runtime/dory-runtime.html",
+    "build:server": "vite build -c vite.config.server.ts",
     "build:cli": "tsc -p tsconfig.bin.json",
     "build:docs": "vite build && vite build --config vite.config.ssr.ts && node scripts/render-routes.mjs",
     "build:embed": "npm run build:embed:loader && npm run build:embed:widget",
@@ -44,46 +51,45 @@
     "build:embed:widget": "vite build -c vite.config.embed-widget.ts",
     "preview": "vite preview",
     "test": "node scripts/check-trigger-children.mjs src && vitest run",
+    "test:runtime-parity": "pnpm run build && node scripts/verify-runtime-parity.mjs",
     "lint:triggers": "node scripts/check-trigger-children.mjs src",
     "publish": "npm run build && npm publish --access public --no-git-checks",
     "prepublishOnly": "echo 'Skipping prepublishOnly - build handled by publish script'"
   },
   "dependencies": {
     "@algolia/autocomplete-core": "1.19.12",
-    "@clidey/ux": "1.5.1",
-    "@fortawesome/fontawesome-svg-core": "7.3.1",
-    "@fortawesome/free-brands-svg-icons": "7.3.1",
-    "@fortawesome/free-regular-svg-icons": "7.3.1",
-    "@fortawesome/free-solid-svg-icons": "7.3.1",
-    "@fortawesome/react-fontawesome": "3.5.0",
+    "@clidey/ux": "1.6.4",
     "@headlessui/react": "2.2.10",
-    "@heroicons/react": "2.2.0",
     "@mdx-js/mdx": "3.1.1",
     "@mdx-js/preact": "3.1.1",
     "@mdx-js/rollup": "3.1.1",
+    "@modelcontextprotocol/node": "2.1.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@preact/preset-vite": "2.10.6",
+    "@resvg/resvg-js": "2.6.2",
     "@tailwindcss/vite": "4.3.3",
     "classnames": "2.5.1",
     "flexsearch": "0.8.212",
     "gray-matter": "4.0.3",
     "katex": "0.19.0",
-    "lucide-react": "1.57.0",
-    "mermaid": "11.16.1",
-    "motion": "12.42.2",
-    "preact": "10.29.8",
+    "mermaid": "12.2.0",
+    "motion": "14.5.0",
+    "playwright-core": "1.64.1",
+    "preact": "11.0.1",
     "preact-render-to-string": "6.8.1",
     "prism-react-renderer": "2.4.1",
-    "react-highlight-words": "0.21.0",
+    "react-highlight-words": "1.0.0",
     "rehype-slug": "6.0.0",
     "remark-gfm": "4.0.1",
-    "sass-embedded": "1.105.1",
+    "sass-embedded": "1.106.0",
     "sirv": "3.0.2",
     "tailwindcss": "4.3.3",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
     "unist-util-visit": "5.1.0",
-    "vite": "8.3.4",
-    "wouter-preact": "3.13.0"
+    "vite": "8.3.5",
+    "wouter-preact": "3.13.0",
+    "zod": "4.6.7"
   },
   "packageManager": "pnpm@12.13.0+sha512.1e55719bf26e809dce5c5084fdebaa64efb3da9038ae5d68a9f8a68311f1a45841c8c3b76a37298c3b66f6bcc80409a9b7f33c78a7168a3e90fb65a5d8235ae4",
   "devDependencies": {

package/scripts/verify-runtime-parity.mjs

@@ -0,0 +1,146 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright-core';
+import { preview } from 'vite';
+
+const root = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const docsRoot = join(root, 'docs');
+const pagePath = 'getting-started/whodb-ee-apps';
+
+function docsFiles(directory = docsRoot) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = join(directory, entry.name);
+    if (entry.isDirectory()) return docsFiles(file);
+    return entry.name.endsWith('.mdx')
+      ? [{ path: `docs/${relative(docsRoot, file).replaceAll('\\', '/')}`, content: readFileSync(file, 'utf8') }]
+      : [];
+  });
+}
+
+const config = JSON.parse(readFileSync(join(docsRoot, 'dory.json'), 'utf8'));
+const logo = readFileSync(join(docsRoot, 'logo/logo.svg')).toString('base64');
+config.logo = {
+  light: `data:image/svg+xml;base64,${logo}`,
+  dark: `data:image/svg+xml;base64,${logo}`,
+};
+
+function visualMetrics() {
+  const measure = selector => {
+    const element = document.querySelector(selector);
+    if (!element) return null;
+    const rect = element.getBoundingClientRect();
+    const style = getComputedStyle(element);
+    return {
+      text: element.textContent?.trim().replace(/\s+/g, ' ').slice(0, 120) ?? '',
+      x: rect.x, y: rect.y, width: rect.width, height: rect.height,
+      font: style.fontFamily, fontSize: style.fontSize, lineHeight: style.lineHeight,
+      weight: style.fontWeight, color: style.color, background: style.backgroundColor,
+      padding: style.padding,
+    };
+  };
+  const article = measure('.dory-article');
+  const headings = [...document.querySelectorAll('.dory-article h1')].map(element => {
+    const rect = element.getBoundingClientRect();
+    const style = getComputedStyle(element);
+    return { text: element.textContent?.trim().replace(/\s+/g, ' ') ?? '', y: rect.y, fontSize: style.fontSize, lineHeight: style.lineHeight };
+  });
+  return {
+    html: measure('html'), header: measure('.dory-topbar'), main: measure('.dory-main'), article,
+    breadcrumb: measure('.dory-breadcrumb'), activeNav: measure('.dory-sidebar-link.active'),
+    topNav: measure('header nav[aria-label]'), firstTab: measure('.dory-topbar-tab'),
+    headerSearch: measure('.dory-topbar-search'), sidebarSearch: measure('#dory-embedded-search'),
+    pageActions: measure('.dory-page-actions'), firstSection: measure('.dory-article h2'),
+    firstParagraph: measure('.dory-article p'), toc: measure('.dory-toc-list'), headings,
+    topTabs: [...document.querySelectorAll('.dory-topbar-tab')].map(element => element.textContent?.trim()),
+  };
+}
+
+const differences = [];
+function equal(label, expected, actual) {
+  if (expected !== actual) differences.push(`${label}: full site ${JSON.stringify(expected)}, embed ${JSON.stringify(actual)}`);
+}
+function near(label, expected, actual, tolerance = 3) {
+  if (typeof expected !== 'number' || typeof actual !== 'number' || Math.abs(expected - actual) > tolerance)
+    differences.push(`${label}: full site ${Math.round(expected ?? NaN)}px, embed ${Math.round(actual ?? NaN)}px`);
+}
+function compare(full, embed, theme) {
+  for (const key of ['html', 'header', 'main', 'article', 'firstSection', 'firstParagraph']) {
+    for (const field of ['background', 'color', 'font', 'fontSize', 'lineHeight']) {
+      equal(`${theme} ${key}.${field}`, full[key]?.[field], embed[key]?.[field]);
+    }
+  }
+  for (const key of ['header', 'main', 'article', 'breadcrumb', 'activeNav', 'topNav', 'firstTab', 'firstSection', 'firstParagraph']) {
+    for (const field of ['x', 'width']) near(`${theme} ${key}.${field}`, full[key]?.[field], embed[key]?.[field]);
+  }
+  equal(`${theme} first tab color`, full.firstTab?.color, embed.firstTab?.color);
+  equal(`${theme} breadcrumb`, full.breadcrumb?.text, embed.breadcrumb?.text);
+  equal(`${theme} top tabs`, full.topTabs.join('|'), embed.topTabs.join('|'));
+  equal(`${theme} page actions present`, Boolean(full.pageActions), Boolean(embed.pageActions));
+  equal(`${theme} topbar search present`, Boolean(full.headerSearch), Boolean(embed.headerSearch));
+  equal(`${theme} sidebar search present`, Boolean(full.sidebarSearch), Boolean(embed.sidebarSearch));
+  equal(`${theme} hero count`, full.headings.length, embed.headings.length);
+  for (let index = 0; index < full.headings.length; index++) {
+    equal(`${theme} hero ${index + 1} text`, full.headings[index]?.text, embed.headings[index]?.text);
+    equal(`${theme} hero ${index + 1} font size`, full.headings[index]?.fontSize, embed.headings[index]?.fontSize);
+    near(`${theme} hero ${index + 1} offset`, full.headings[index]?.y - full.article.y, embed.headings[index]?.y - embed.article.y);
+  }
+  for (const key of ['firstSection', 'firstParagraph', 'activeNav'])
+    near(`${theme} ${key} vertical offset`, full[key]?.y - full.article.y, embed[key]?.y - embed.article.y);
+}
+
+const server = process.env.DORY_PARITY_ORIGIN ? null : await preview({
+  root,
+  preview: { host: '127.0.0.1', port: 0 },
+});
+const port = server?.httpServer.address()?.port;
+const origin = process.env.DORY_PARITY_ORIGIN ?? `http://127.0.0.1:${port}`;
+let browser;
+try {
+  browser = await chromium.launch({ channel: 'chrome', headless: true });
+  for (const theme of ['light', 'dark']) {
+    const full = await browser.newPage({ viewport: { width: 2048, height: 1200 } });
+    await full.goto(`${origin}/${pagePath}`, { waitUntil: 'networkidle' });
+    if (theme === 'dark') await full.locator('html').evaluate(element => { element.classList.remove('light'); element.classList.add('dark'); });
+    await full.evaluate(() => document.fonts.ready);
+    const fullMetrics = await full.evaluate(visualMetrics);
+
+    const embed = await browser.newPage({ viewport: { width: 2048, height: 1200 } });
+    await embed.goto(`${origin}/runtime/dory-runtime.html`, { waitUntil: 'networkidle' });
+    await embed.evaluate(({ files, config, theme, pagePath }) => {
+      window.postMessage({ __dory_docs: true, type: 'load', files, path: `docs/${pagePath}.mdx`, theme, locale: 'en_US', config }, '*');
+    }, { files: docsFiles(), config, theme, pagePath });
+    await embed.getByRole('heading', { name: 'Document WhoDB EE apps' }).waitFor();
+    await embed.evaluate(() => document.fonts.ready);
+    const embedMetrics = await embed.evaluate(visualMetrics);
+    compare(fullMetrics, embedMetrics, theme);
+    if (differences.length || process.env.DORY_PARITY_SCREENSHOTS === '1') {
+      await full.screenshot({ path: `/tmp/dory-parity-full-${theme}.png` });
+      await embed.screenshot({ path: `/tmp/dory-parity-embed-${theme}.png` });
+    }
+    await embed.evaluate(({ files, config, theme }) => {
+      window.postMessage({ __dory_docs: true, type: 'load', files, path: 'docs/components/accordion.mdx', theme, locale: 'en_US', config }, '*');
+    }, { files: docsFiles(), config, theme });
+    await embed.getByRole('heading', { name: 'Accordion', exact: true }).first().waitFor();
+    const specimen = embed.locator('.dory-specimen').first();
+    await specimen.getByRole('tab', { name: 'Code' }).click();
+    await specimen.locator('pre').first().waitFor();
+    await specimen.getByRole('tab', { name: 'Preview' }).click();
+    await embed.evaluate(({ files, config, theme }) => {
+      window.postMessage({ __dory_docs: true, type: 'load', files, path: 'docs/components/icons.mdx', theme, locale: 'en_US', config }, '*');
+    }, { files: docsFiles(), config, theme });
+    await embed.locator('button[title^="Copy <Icon"]').first().waitFor();
+    await full.close();
+    await embed.close();
+  }
+  if (differences.length) {
+    console.error(`Dory embedded runtime differs from the full docs site:\n${differences.map(item => `- ${item}`).join('\n')}`);
+    console.error('Screenshots: /tmp/dory-parity-{full,embed}-{light,dark}.png');
+    process.exitCode = 1;
+  } else {
+    console.log('Dory full site and embedded runtime visual parity passed in light and dark mode.');
+  }
+} finally {
+  await browser?.close();
+  await new Promise(resolve => server?.httpServer.close(resolve) ?? resolve());
+}

package/src/app.css

@@ -1,5 +1,23 @@
-@import "tailwindcss";
+/* UX supplies the shared reset. Dory adds its own generated utilities. */
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
 
 @custom-variant dark (&:where(.dark, .dark *));
 
+.mermaid-wrapper .mermaid svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin-inline: auto;
+}
+
+@media (max-width: 480px) {
+  /* Keep the UX 404 illustration inside its narrow stage. Its animation sets left inline. */
+  .ux-not-found-character {
+    left: clamp(80px, 24vw, 100px) !important;
+    scale: .6;
+  }
+}
+
 

package/src/assets/fonts/OFL.txt

@@ -0,0 +1,94 @@
+Copyright 2021 The Hanken Grotesk Project Authors (https://github.com/marcologous/hanken-grotesk)
+
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/components/chat-assistant.tsx

@@ -0,0 +1,229 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { withBase } from '../utils/base-path';
+import { captureDocsEvent } from '../utils/analytics';
+
+import { CatalogIcon, Button, CopyButton, copyToClipboard } from '@clidey/ux';
+import docsConfig from '../../docs/dory.json' with { type: 'json' };
+import type { DoryConfig } from '../types/config';
+
+export type Citation = { id: string; title: string; url: string; excerpt: string };
+export type Message = { role: 'user' | 'assistant'; content: string; citations?: Citation[]; followUps?: string[] };
+export type ChatTransport = {
+  status: () => Promise<boolean>;
+  ask: (message: string, history: Pick<Message, 'role' | 'content'>[], pathname: string, signal: AbortSignal) => Promise<{ answer?: string; citations?: Citation[]; followUps?: string[]; error?: string }>;
+};
+
+class ChatRequestError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) { super(message); this.status = status; }
+}
+
+const defaultTransport: ChatTransport = {
+  async status() {
+    const response = await fetch(withBase('/api/chat/status'), { credentials: 'same-origin' });
+    if (!response.headers.get('content-type')?.includes('application/json')) return false;
+    const status = await response.json();
+    return status?.enabled === true;
+  },
+  async ask(message, history, pathname, signal) {
+    const response = await fetch(withBase('/api/chat'), {
+      method: 'POST', credentials: 'same-origin', signal,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message, history, pathname }),
+    });
+    const result = await response.json() as { answer?: string; citations?: Citation[]; followUps?: string[]; error?: string };
+    if (!response.ok) throw new ChatRequestError(result.error || 'The answer is unavailable right now.', response.status);
+    return result;
+  },
+};
+
+const site = docsConfig as DoryConfig;
+const suggestedQuestions = Array.isArray(site.chat?.suggestedQuestions)
+  ? site.chat.suggestedQuestions.filter(question => typeof question === 'string' && question.trim().length >= 3 && question.trim().length <= 600).slice(0, 4)
+  : [];
+const starters = suggestedQuestions?.length ? suggestedQuestions : [
+  `How do I get started with ${site.name}?`,
+  `What can I do with ${site.name}?`,
+  'Explain this page',
+];
+
+function renderInline(text: string) {
+  return text.split(/(\*\*[^*]+\*\*|`[^`]+`)/g).map((part, index) => {
+    if (part.startsWith('**') && part.endsWith('**')) return <strong key={index}>{part.slice(2, -2)}</strong>;
+    if (part.startsWith('`') && part.endsWith('`')) return <code key={index} className="rounded bg-[var(--accent)] px-1 py-0.5 font-mono text-[0.9em]">{part.slice(1, -1)}</code>;
+    return part;
+  });
+}
+
+function AnswerText({ text }: { text: string }) {
+  return <div className="space-y-3 text-sm leading-7 text-foreground sm:text-base">{text.split(/(```[^\n]*\n[\s\S]*?```)/g).map((part, index) => {
+    if (part.startsWith('```') && part.endsWith('```')) {
+      const language = part.slice(3, part.indexOf('\n')).trim();
+      const code = part.slice(part.indexOf('\n') + 1, -3).trimEnd();
+      return <div key={index} className="overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--accent)]">
+        <div className="flex items-center justify-between border-b border-[var(--border)] px-3 py-1 text-xs text-muted-foreground">
+          <span>{language || 'Code'}</span>
+          <CopyButton text={code} tooltipLabel="Copy code" copiedLabel="Code copied" onCopy={() => captureDocsEvent('docs_chat_code_copied', { path: window.location.pathname })} />
+        </div>
+        <pre className="overflow-x-auto p-4 text-sm leading-6"><code>{code}</code></pre>
+      </div>;
+    }
+    return part.split(/\n\s*\n/).filter(Boolean).map((paragraph, paragraphIndex) => <p key={`${index}-${paragraphIndex}`} className="whitespace-pre-wrap">{renderInline(paragraph.trim())}</p>);
+  })}</div>;
+}
+
+function CopyAnswerButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+  useEffect(() => {
+    if (!copied) return;
+    const timeout = window.setTimeout(() => setCopied(false), 2000);
+    return () => window.clearTimeout(timeout);
+  }, [copied]);
+
+  return <Button type="button" variant="ghost" size="sm" className="gap-2 text-xs text-muted-foreground" onClick={async () => {
+    if (await copyToClipboard(text)) {
+      setCopied(true);
+      captureDocsEvent('docs_chat_answer_copied', { path: window.location.pathname });
+    }
+  }}>
+    <CatalogIcon name={copied ? 'check' : 'copy'} className="h-4 w-4" />
+    {copied ? 'Copied' : 'Copy answer'}
+  </Button>;
+}
+
+export function useChatAssistant(options: { transport?: ChatTransport; initialMessages?: Message[]; initialDraft?: string; onMessagesChange?: (messages: Message[]) => void } = {}) {
+  const transport = options.transport ?? defaultTransport;
+  const [enabled, setEnabled] = useState(false);
+  const [messages, setMessages] = useState<Message[]>(options.initialMessages ?? []);
+  const [draft, setDraft] = useState(options.initialDraft ?? '');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+  const controller = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    transport.status()
+      .then(setEnabled)
+      .catch(() => setEnabled(false));
+    return () => controller.current?.abort();
+  }, []);
+  useEffect(() => { options.onMessagesChange?.(messages); }, [messages]);
+
+  function reset() {
+    controller.current?.abort();
+    controller.current = null;
+    setMessages([]);
+    setDraft('');
+    setError('');
+    setBusy(false);
+  }
+
+  async function ask(question = draft) {
+    const text = question.trim();
+    if (busy || text.length < 3 || text.length > 600) return;
+    const previous = messages.slice(-6).map(({ role, content }) => ({ role, content }));
+    setMessages(current => [...current, { role: 'user', content: text }]);
+    setDraft('');
+    setError('');
+    setBusy(true);
+    captureDocsEvent('docs_chat_question', { path: window.location.pathname, question_length: text.length });
+    let errorKind = 'network';
+    const request = new AbortController();
+    controller.current = request;
+    try {
+      const result = await transport.ask(text, previous, window.location.pathname, request.signal);
+      if (!result.answer) { errorKind = 'invalid_answer'; throw new Error(result.error || 'The answer is unavailable right now.'); }
+      if (!request.signal.aborted) {
+        setMessages(current => [...current, { role: 'assistant', content: result.answer!, citations: result.citations, followUps: result.followUps }]);
+        captureDocsEvent('docs_chat_answer', { path: window.location.pathname, citation_count: result.citations?.length ?? 0 });
+      }
+    } catch (cause) {
+      if (!request.signal.aborted) {
+        if (cause instanceof ChatRequestError) errorKind = cause.status === 429 ? 'rate_limited' : 'server_error';
+        setError(cause instanceof Error ? cause.message : 'The answer is unavailable right now.');
+        captureDocsEvent('docs_chat_error', { path: window.location.pathname, error_kind: errorKind });
+      }
+    } finally {
+      if (controller.current === request) {
+        controller.current = null;
+        setBusy(false);
+      }
+    }
+  }
+
+  return { enabled, messages, draft, setDraft, busy, error, ask, reset };
+}
+
+export function ChatAssistant({ chat, onNavigate, onSearch, siteName = site.name, questions = starters, intro, onSourceClick }: {
+  chat: ReturnType<typeof useChatAssistant>;
+  onNavigate: () => void;
+  onSearch: () => void;
+  siteName?: string;
+  questions?: string[];
+  intro?: string;
+  onSourceClick?: (source: Citation) => void;
+}) {
+  const bottom = useRef<HTMLDivElement>(null);
+  const input = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => { input.current?.focus(); }, [chat.messages.length === 0]);
+  useEffect(() => bottom.current?.scrollIntoView({ behavior: 'smooth', block: 'end' }), [chat.messages, chat.busy]);
+
+  const composer = (
+    <form className="dory-chat-composer border-t border-[var(--border)] p-4 sm:px-6" onSubmit={event => { event.preventDefault(); chat.ask(); }}>
+      <label htmlFor="dory-chat-question" className="sr-only">Your documentation question</label>
+      <div className="flex items-end gap-2 rounded-xl border border-[var(--border)] bg-[var(--background)] px-3 py-2 focus-within:border-[var(--brand-primary)]">
+        <textarea id="dory-chat-question" ref={input} value={chat.draft} onInput={event => chat.setDraft(event.currentTarget.value)} onKeyDown={event => { if (event.key === 'Enter' && !event.shiftKey) { event.preventDefault(); chat.ask(); } else if (event.key === 'Tab' && !event.shiftKey) { event.preventDefault(); onSearch(); } }} rows={1} maxLength={600} placeholder={chat.messages.length ? 'Ask a follow-up' : `Ask Dory anything about ${siteName}`} className="max-h-28 min-h-10 flex-1 resize-none bg-transparent px-2 py-2 text-sm outline-none" />
+        <button type="button" disabled={chat.busy || chat.draft.trim().length < 3} onClick={() => void chat.ask()} className="rounded-lg bg-[var(--brand-primary)] px-3 py-2 text-sm font-semibold text-white disabled:opacity-40" aria-label="Send question">↑</button>
+      </div>
+      {chat.messages.length > 0 && <p className="mt-2 text-center text-[11px] text-muted-foreground">Sources are linked when the docs support an answer. Check important details on the page.</p>}
+    </form>
+  );
+
+  return (
+    <div className={`dory-search-chat flex flex-col ${chat.messages.length === 0 ? 'h-[min(58vh,480px)]' : 'h-[min(78vh,640px)] sm:h-[min(72vh,620px)]'}`}>
+      {chat.messages.length === 0 && composer}
+      <div className="min-h-0 flex-1 overflow-y-auto px-5 py-6 sm:px-8" aria-live="polite">
+        {chat.messages.length === 0 && (
+          <div className="space-y-5">
+            <p className="text-sm leading-6 text-muted-foreground">{intro ?? 'Ask in plain language. Dory reads these docs and answers with links to the sections it used.'}</p>
+            <div className="grid gap-2">
+              {questions.map(prompt => <button key={prompt} type="button" onClick={() => chat.ask(prompt)} className="flex items-center gap-3 rounded-lg px-3 py-2 text-left text-sm hover:bg-[var(--accent)]"><CatalogIcon name="arrow-up-right" className="h-4 w-4 shrink-0 text-[var(--primary)]" /><span>{prompt}</span></button>)}
+            </div>
+          </div>
+        )}
+        <div className="space-y-6">
+          {chat.messages.map((message, index) => (
+            <div key={index} className="space-y-3">
+              {message.role === 'user' ? (
+                <h2 className="text-xl font-semibold leading-snug text-foreground">{message.content}</h2>
+              ) : (
+                <div className="dory-chat-answer space-y-4">
+                  <AnswerText text={message.content} />
+                  <CopyAnswerButton text={message.content} />
+                  {message.citations && message.citations.length > 0 && (
+                    <div className="space-y-2 pt-2">
+                      <p className="text-xs font-semibold uppercase tracking-widest text-muted-foreground">Sources</p>
+                      <div className="flex flex-wrap gap-2">
+                        {message.citations.map((source, sourceIndex) => <a key={source.id} href={onSourceClick ? '#' : withBase(source.url)} onClick={event => { if (onSourceClick) { event.preventDefault(); onSourceClick(source); } else { captureDocsEvent('docs_chat_source_clicked', { path: window.location.pathname, source: source.url }); onNavigate(); } }} className="min-w-36 rounded-lg border border-[var(--border)] px-3 py-2 hover:bg-[var(--accent)]">
+                          <span className="block text-sm font-medium text-foreground"><span className="mr-2 text-[var(--brand-primary)]">{sourceIndex + 1}</span>{source.title}</span>
+                          {source.excerpt && <span className="mt-1 block line-clamp-2 text-xs text-muted-foreground">{source.excerpt}</span>}
+                        </a>)}
+                      </div>
+                    </div>
+                  )}
+                  {message.followUps && message.followUps.length > 0 && (
+                    <div className="flex flex-wrap gap-2 pt-2">{message.followUps.map(prompt => <button key={prompt} type="button" onClick={() => chat.ask(prompt)} disabled={chat.busy} className="rounded-full border border-[var(--border)] px-3 py-1.5 text-xs hover:bg-[var(--accent)] disabled:opacity-50">→ &nbsp; {prompt}</button>)}</div>
+                  )}
+                </div>
+              )}
+            </div>
+          ))}
+          {chat.busy && <p className="text-sm text-muted-foreground" role="status">Reading the docs and checking sources…</p>}
+          {chat.error && <p className="rounded-lg bg-red-500/10 p-3 text-sm text-red-700 dark:text-red-300" role="alert">{chat.error}</p>}
+          <div ref={bottom} />
+        </div>
+      </div>
+      {chat.messages.length > 0 && composer}
+    </div>
+  );
+}

package/src/components/dropdown.tsx

@@ -1,4 +1,4 @@
-import {
+import { CatalogIcon,
   DropdownMenu,
   DropdownMenuTrigger,
   DropdownMenuContent,
@@ -6,7 +6,7 @@ import {
   DropdownMenuSeparator,
   Button
 } from '@clidey/ux'
-import { ChevronDownIcon } from '@heroicons/react/20/solid'
+
 import type { ComponentChildren } from 'preact'
 import type { ReactNode } from 'preact/compat'
 
@@ -30,7 +30,7 @@ export default function Dropdown({ buttonLabel, items, className = '' }: Dropdow
       <DropdownMenuTrigger>
         <Button className={className}>
           {buttonLabel}
-          <ChevronDownIcon className="ml-2 h-4 w-4" />
+          <CatalogIcon name="chevron-down" className="ml-2 h-4 w-4" />
         </Button>
       </DropdownMenuTrigger>
       <DropdownMenuContent>

package/src/components/error-boundary.tsx

@@ -1,5 +1,5 @@
+import { CatalogIcon } from '@clidey/ux'
 import { Component, type ComponentChildren } from 'preact';
-import { ExclamationTriangleIcon } from '@heroicons/react/24/outline';
 
 interface ErrorBoundaryProps {
   children: ComponentChildren;
@@ -33,7 +33,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
       return (
         <div className="flex flex-col items-center justify-center min-h-[50vh] p-8">
           <div className="w-16 h-16 mb-4 flex items-center justify-center bg-red-100 dark:bg-red-900/30 rounded-full">
-            <ExclamationTriangleIcon className="w-8 h-8 text-red-500" />
+            <CatalogIcon name="warning" className="w-8 h-8 text-red-500" />
           </div>
           <h2 className="text-2xl font-semibold text-red-700 dark:text-red-300 mb-2">
             Something went wrong