@clidey/dory 1.0.8 → 1.9.0

package/src/ui/table-of-content-view.tsx

@@ -0,0 +1,167 @@
+import { CatalogIcon } from '@clidey/ux'
+import { useEffect, useState } from 'preact/hooks'
+import classNames from 'classnames'
+
+// A heading counts as current once it scrolls below the sticky top bar.
+const ACTIVE_OFFSET = 120
+
+type Heading = {
+  id: string
+  title: string
+  level: 2 | 3
+}
+
+export type TableOfContentsLabels = {
+  onThisPage?: string
+  editThisPage?: string
+  reportIssue?: string
+  backToTop?: string
+}
+
+export type TableOfContentsViewProps = {
+  pageKey: string
+  editUrl?: string | null
+  issueUrl?: string | null
+  labels?: TableOfContentsLabels
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+    .replace(/\s+/g, '-')
+}
+
+function headingText(heading: Element): string {
+  return Array.from(heading.childNodes)
+    .filter(node => !(node instanceof Element && node.classList.contains('dory-anchor')))
+    .map(node => node.textContent ?? '')
+    .join('')
+    .trim()
+}
+
+function collectHeadings(article: Element): Heading[] {
+  const headings: Heading[] = []
+  article.querySelectorAll('h2, h3').forEach(heading => {
+    if (heading.closest('.dory-specimen') || heading.hasAttribute('data-toc-ignore')) return
+    const title = headingText(heading)
+    const id = heading.id || slugify(title)
+    if (!id) return
+    if (!heading.id) heading.id = id
+    headings.push({ id, title, level: heading.tagName === 'H2' ? 2 : 3 })
+  })
+  return headings
+}
+
+/** The shared Dory heading rail used by the site and the app documentation viewer. */
+export function TableOfContentsView({ pageKey, editUrl, issueUrl, labels }: TableOfContentsViewProps) {
+  const [headings, setHeadings] = useState<Heading[]>([])
+  const [currentId, setCurrentId] = useState('')
+  const [progress, setProgress] = useState(0)
+
+  useEffect(() => {
+    const article = document.querySelector('.dory-article')
+    if (!article) return
+    const update = () => setHeadings(collectHeadings(article))
+    update()
+    // Mermaid and other components may add their headings after mount.
+    const observer = new MutationObserver(update)
+    observer.observe(article, { childList: true, subtree: true })
+    return () => observer.disconnect()
+  }, [pageKey])
+
+  useEffect(() => {
+    function onScroll() {
+      const scrollable = document.documentElement.scrollHeight - window.innerHeight
+      const ratio = scrollable > 0 ? Math.min(1, window.scrollY / scrollable) : 1
+      setProgress(Math.round(ratio * 100))
+
+      let current = headings[0]?.id ?? ''
+      if (ratio >= 1 && headings.length > 0) {
+        current = headings[headings.length - 1].id
+      } else {
+        for (const heading of headings) {
+          const el = document.getElementById(heading.id)
+          if (el && el.getBoundingClientRect().top <= ACTIVE_OFFSET) current = heading.id
+          else if (el) break
+        }
+      }
+      setCurrentId(current)
+    }
+
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    window.addEventListener('resize', onScroll)
+    return () => {
+      window.removeEventListener('scroll', onScroll)
+      window.removeEventListener('resize', onScroll)
+    }
+  }, [headings])
+
+  let sectionNumber = 0
+
+  return (
+    <aside className="dory-toc hidden w-52 shrink-0 xl:block" aria-labelledby="on-this-page-title">
+      {headings.length > 0 && (
+        <div className="sticky top-24 max-h-[calc(100vh-7rem)] overflow-y-auto pb-6">
+          <div className="flex items-center justify-between">
+            <h2 id="on-this-page-title" className="dory-toc-label">{labels?.onThisPage ?? 'On this page'}</h2>
+            <span className="dory-toc-label">{progress}%</span>
+          </div>
+          <div className="dory-toc-track mt-2.5" aria-hidden="true">
+            <div className="dory-toc-fill" style={{ width: `${progress}%` }} />
+          </div>
+
+          <ol role="list" className="dory-toc-list mt-5">
+            {headings.map(heading => {
+              if (heading.level === 2) sectionNumber += 1
+              return (
+                <li key={heading.id}>
+                  <a
+                    href={`#${heading.id}`}
+                    aria-current={heading.id === currentId ? 'location' : undefined}
+                    className={classNames('dory-toc-link', {
+                      active: heading.id === currentId,
+                      'dory-toc-sub': heading.level === 3,
+                    })}
+                  >
+                    {heading.level === 2 && (
+                      <span className="dory-toc-number">{String(sectionNumber).padStart(2, '0')}</span>
+                    )}
+                    <span>{heading.title}</span>
+                  </a>
+                </li>
+              )
+            })}
+          </ol>
+
+          <div className="dory-toc-actions mt-6 space-y-2.5 border-t border-[var(--border)] pt-5">
+            {editUrl && (
+              <a href={editUrl} target="_blank" rel="noopener noreferrer">
+                <CatalogIcon name="edit" aria-hidden="true" className="h-3.5 w-3.5" />
+                {labels?.editThisPage ?? 'Edit this page'}
+              </a>
+            )}
+            {issueUrl && (
+              <a href={issueUrl} target="_blank" rel="noopener noreferrer">
+                <CatalogIcon name="alert-circle" aria-hidden="true" className="h-3.5 w-3.5" />
+                {labels?.reportIssue ?? 'Report an issue'}
+              </a>
+            )}
+            <a
+              href="#"
+              onClick={event => {
+                event.preventDefault()
+                window.scrollTo({ top: 0, behavior: 'smooth' })
+              }}
+            >
+              <CatalogIcon name="chevron-up" aria-hidden="true" className="h-3.5 w-3.5" />
+              {labels?.backToTop ?? 'Back to top'}
+            </a>
+          </div>
+        </div>
+      )}
+    </aside>
+  )
+}

package/src/ui/table-of-content.tsx

@@ -1,192 +1,34 @@
-import { useCallback, useEffect, useState } from 'react'
-import classNames from 'classnames'
-
-/**
- * Slugifies heading text matching rehype-slug (github-slugger) behavior:
- * lowercase, strip punctuation, spaces to dashes. Used only as a fallback
- * for headings that did not get an id at build time, so client-assigned
- * anchors agree with SSR-assigned ones.
- */
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .trim()
-    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
-    .replace(/\s+/g, '-')
-}
-
-export type Section = {
-  id: string
-  title: string
-  children: Array<Subsection>
+import { useEffect, useState } from 'preact/hooks'
+import docsConfig from '../../docs/dory.json' with { type: 'json' }
+import type { DoryConfig } from '../types/config'
+import { usePathname } from '../components/hooks'
+import { TableOfContentsView } from './table-of-content-view'
+
+const config = docsConfig as DoryConfig
+
+function editUrl(pathname: string) {
+  const repo = config.repository
+  if (!repo) return null
+  const dir = repo.path ? `${repo.path.replace(/\/$/, '')}/` : ''
+  return `${repo.url}/edit/${repo.branch ?? 'main'}/${dir}${pathname.replace(/^\//, '')}.mdx`
 }
 
-export type Subsection = {
-  id: string
-  title: string
+function issueUrl() {
+  const repo = config.repository
+  if (!repo) return null
+  const title = encodeURIComponent(`Docs: ${document.title}`)
+  const body = encodeURIComponent(`Page: ${window.location.origin}${window.location.pathname}`)
+  return `${repo.url}/issues/new?title=${title}&body=${body}`
 }
 
+/** Site TOC with repository actions; the embedded viewer uses the shared view directly. */
 export function TableOfContents() {
-  const [currentSection, setCurrentSection] = useState<string>('')
-  const [sections, setSections] = useState<Section[]>([])
-  const [isContentLoaded, setIsContentLoaded] = useState(false)
-
-  const collectHeadings = useCallback(() => {
-    const article = document.querySelector('article')
-    if (!article) return
-
-    // Wait for content to be loaded
-    const observer = new MutationObserver(() => {
-      const headings = article.querySelectorAll('h2:not([style*="display: none"]), h3:not([style*="display: none"])')
-      const sections: Section[] = []
-      let currentSection: Section | null = null
-
-      // Heading text without the trailing "#" anchor link
-      const headingText = (heading: Element) =>
-        Array.from(heading.childNodes)
-          .filter((node) => !(node instanceof Element && node.classList.contains('dory-anchor')))
-          .map((node) => node.textContent ?? '')
-          .join('')
-          .trim()
-
-      headings.forEach((heading) => {
-        // Check if heading is a valid Element and is visible
-        if (!(heading instanceof Element)) return
-        const style = window.getComputedStyle(heading)
-        if (style.display === 'none' || style.visibility === 'hidden') return
-
-        // Prefer the build-time id from rehype-slug; only assign when missing
-        const id = heading.id || slugify(headingText(heading))
-        if (!heading.id && id) {
-          heading.id = id
-        }
-
-        if (heading.tagName === 'H2') {
-          currentSection = {
-            id,
-            title: headingText(heading),
-            children: []
-          }
-          sections.push(currentSection)
-        } else if (heading.tagName === 'H3' && currentSection) {
-          currentSection.children.push({
-            id,
-            title: headingText(heading)
-          })
-        }
-      })
-
-      setSections(sections)
-      setIsContentLoaded(true)
-    })
-
-    observer.observe(article, { 
-      childList: true, 
-      subtree: true,
-      attributes: true,
-      attributeFilter: ['style', 'class']
-    })
-
-    return () => observer.disconnect()
-  }, [])
+  const pathname = usePathname()
+  const [links, setLinks] = useState<{ edit: string | null; issue: string | null }>({ edit: null, issue: null })
 
   useEffect(() => {
-    const cleanup = collectHeadings()
-    return () => cleanup?.()
-  }, [collectHeadings])
-
-  const getHeadings = useCallback(() => {
-    return sections
-      .flatMap((section) => [section.id, ...section.children.map((child) => child.id)])
-      .map((id) => {
-        const el = document.getElementById(id)
-        if (!el) return null
-        const top = window.scrollY + el.getBoundingClientRect().top
-        return { id, top }
-      })
-      .filter((x): x is { id: string; top: number } => x !== null)
-  }, [sections])
-
-  useEffect(() => {
-    if (!isContentLoaded || sections.length === 0) return
-    const headings = getHeadings()
-    
-    function onScroll() {
-      const top = window.scrollY
-      let current = headings[0].id
-      for (const heading of headings) {
-        if (top >= heading.top - 10) {
-          current = heading.id
-        } else {
-          break
-        }
-      }
-      setCurrentSection(current)
-    }
-
-    window.addEventListener('scroll', onScroll, { passive: true })
-    onScroll()
-    return () => {
-      window.removeEventListener('scroll', onScroll)
-    }
-  }, [getHeadings, sections, isContentLoaded])
-
-  function isActive(section: Section | Subsection) {
-    return section.id === currentSection
-  }
-
-  if (!isContentLoaded) {
-    return null
-  }
+    setLinks({ edit: editUrl(pathname), issue: issueUrl() })
+  }, [pathname])
 
-  return (
-    <div className="hidden xl:sticky xl:top-[4.75rem] xl:-mr-6 xl:block xl:h-[calc(100vh-4.75rem)] xl:flex-none xl:overflow-y-auto xl:py-16 xl:pr-6 pl-8">
-      <nav aria-labelledby="on-this-page-title" className="w-56">
-        {sections.length > 0 && (
-          <>
-            <h2
-              id="on-this-page-title"
-              className="font-display text-sm font-medium text-foreground dark:text-white"
-            >
-              On this page
-            </h2>
-            <ol role="list" className="mt-4 space-y-3 text-sm">
-              {sections.map((section) => (
-                <li key={section.id}>
-                  <h3>
-                    <a
-                      href={`#${section.id}`}
-                      className={classNames({
-                        "text-brand-foreground": isActive(section),
-                        "font-normal text-muted-foreground hover:text-foreground/80 dark:hover:text-slate-300": !isActive(section),
-                      })}>
-                      {section.title}
-                    </a>
-                  </h3>
-                  {section.children.length > 0 && (
-                    <ol role="list" className="mt-2 space-y-3 pl-5 text-muted-foreground dark:text-muted-foreground">
-                      {section.children.map((subSection) => (
-                        <li key={subSection.id}>
-                          <a
-                            href={`#${subSection.id}`}
-                            className={
-                              isActive(subSection)
-                                ? 'text-brand-foreground'
-                                : 'hover:text-muted-foreground dark:hover:text-slate-300'
-                            }
-                          >
-                            {subSection.title}
-                          </a>
-                        </li>
-                      ))}
-                    </ol>
-                  )}
-                </li>
-              ))}
-            </ol>
-          </>
-        )}
-      </nav>
-    </div>
-  )
+  return <TableOfContentsView pageKey={pathname} editUrl={links.edit} issueUrl={links.issue} />
 }

package/src/utils/analytics.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('documentation analytics delivery', () => {
+  beforeEach(() => vi.resetModules())
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('sends a redacted search query to PostHog without contacting a Dory server', async () => {
+    const capture = vi.fn()
+    const fetch = vi.fn()
+    vi.stubGlobal('window', { posthog: { capture } })
+    vi.stubGlobal('fetch', fetch)
+    const { captureDocsEvent } = await import('./analytics')
+
+    captureDocsEvent('docs_search', { query: 'api key=short123 email me@example.com', result_count: 0, path: '/intro' })
+    expect(capture).toHaveBeenCalledOnce()
+    expect(capture).toHaveBeenCalledWith('docs_search', expect.objectContaining({
+      query: expect.not.stringContaining('short123'),
+      result_count: 0,
+      path: '/intro',
+    }))
+    expect(capture.mock.calls[0][1].query).not.toContain('me@example.com')
+    expect(fetch).not.toHaveBeenCalled()
+  })
+
+  it('does not require a Dory analytics server', async () => {
+    const capture = vi.fn()
+    const fetch = vi.fn()
+    vi.stubGlobal('window', { posthog: { capture } })
+    vi.stubGlobal('fetch', fetch)
+    const { captureDocsEvent } = await import('./analytics')
+
+    captureDocsEvent('docs_code_copied', { path: '/intro' })
+    expect(capture).toHaveBeenCalledOnce()
+    expect(fetch).not.toHaveBeenCalled()
+  })
+})

package/src/utils/analytics.ts

@@ -0,0 +1,35 @@
+declare global {
+  interface Window {
+    posthog?: { capture: (event: string, properties?: Record<string, unknown>) => void }
+  }
+}
+
+type DocsEvent =
+  | 'docs_search'
+  | 'docs_search_result_clicked'
+  | 'docs_page_feedback'
+  | 'docs_code_copied'
+  | 'docs_page_engaged'
+  | 'docs_chat_opened'
+  | 'docs_chat_question'
+  | 'docs_chat_answer'
+  | 'docs_chat_answer_copied'
+  | 'docs_chat_code_copied'
+  | 'docs_chat_error'
+  | 'docs_chat_source_clicked'
+
+/** Search text may contain credentials or personal data typed by mistake. */
+function sanitizeQuery(value: string): string {
+  return value.trim().slice(0, 160)
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[email]')
+    .replace(/\b(?:Bearer\s+\S+|sk-[A-Za-z0-9_-]{12,}|(?:api[\s_-]?key|token|password|secret)\s*[:=]\s*\S+)/gi, '[redacted]')
+}
+
+/** Sends a small event to the configured PostHog project. */
+export function captureDocsEvent(event: DocsEvent, properties: Record<string, unknown>): void {
+  if (typeof window === 'undefined') return
+  const safeProperties = { ...properties }
+  if (typeof safeProperties.query === 'string') safeProperties.query = sanitizeQuery(safeProperties.query)
+  try { window.posthog?.capture(event, safeProperties) }
+  catch { /* Analytics must not interrupt reading. */ }
+}

package/src/utils/colors.ts

@@ -16,6 +16,13 @@ export function loadColors() {
   if (!colors) return;
 
   const root = document.documentElement;
+  const light = colors.light || colors.primary;
+  const dark = colors.dark || colors.primary;
+  if (light || dark) {
+    root.setAttribute('data-dory-colors', 'true');
+    root.style.setProperty('--brand-light', light || dark);
+    root.style.setProperty('--brand-dark', dark || light);
+  }
 
   // Brand accent colors
   if (colors.primary) {

package/src/utils/content-scope.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { contentScope, scopedPath } from './content-scope';
+import type { DoryConfig } from '../types/config';
+
+const navigation = { tabs: [{ tab: 'Guides', groups: [{ group: 'Start', pages: ['intro'] }] }] };
+const config = {
+  name: 'Example', favicon: 'favicon.svg', logo: { light: 'logo.svg', dark: 'logo.svg' },
+  navigation,
+  i18n: { defaultLocale: 'en', locales: [{ code: 'en', label: 'English' }, { code: 'fr', label: 'Français' }] },
+  versions: [{ id: 'v1', label: 'Version 1' }],
+} satisfies DoryConfig;
+
+describe('content scope', () => {
+  it('preserves current URLs for the default language and version', () => {
+    expect(contentScope(config, '/intro')).toMatchObject({ locale: 'en', version: '', prefix: '', page: '/intro' });
+  });
+
+  it('resolves a translated, versioned page', () => {
+    expect(contentScope(config, '/fr/v1/intro')).toMatchObject({ locale: 'fr', version: 'v1', prefix: '/fr/v1', page: '/intro' });
+  });
+
+  it('keeps the page when switching language and version', () => {
+    expect(scopedPath(config, '/fr/v1/intro', 'en', '')).toBe('/intro');
+    expect(scopedPath(config, '/intro', 'fr', 'v1')).toBe('/fr/v1/intro');
+  });
+});

package/src/utils/content-scope.ts

@@ -0,0 +1,39 @@
+import type { DoryConfig, DoryNavigation } from '../types/config.ts';
+
+export interface ContentScope {
+  locale: string;
+  version: string;
+  prefix: string;
+  page: string;
+  navigation: DoryNavigation;
+}
+
+/** Content lives at the route it publishes: docs/fr/intro.mdx -> /fr/intro. */
+export function contentScope(config: DoryConfig, pathname: string): ContentScope {
+  const parts = pathname.split('/').filter(Boolean);
+  const locales = config.i18n?.locales ?? [];
+  const defaultLocale = config.i18n?.defaultLocale ?? locales[0]?.code ?? 'en';
+  const localeEntry = locales.find(entry => entry.code === parts[0] && entry.code !== defaultLocale);
+  if (localeEntry) parts.shift();
+
+  const versionEntry = config.versions?.find(entry => entry.id && entry.id === parts[0]);
+  if (versionEntry) parts.shift();
+
+  const locale = localeEntry?.code ?? defaultLocale;
+  const version = versionEntry?.id ?? '';
+  const prefix = [localeEntry?.code, version].filter(Boolean).map(segment => `/${segment}`).join('');
+  return {
+    locale,
+    version,
+    prefix,
+    page: `/${parts.join('/')}`,
+    navigation: (version ? localeEntry?.versions?.[version] : undefined) ?? localeEntry?.navigation ?? versionEntry?.navigation ?? config.navigation,
+  };
+}
+
+export function scopedPath(config: DoryConfig, pathname: string, locale: string, version: string): string {
+  const current = contentScope(config, pathname);
+  const defaultLocale = config.i18n?.defaultLocale ?? config.i18n?.locales[0]?.code ?? 'en';
+  const prefix = [locale !== defaultLocale ? locale : '', version].filter(Boolean).map(segment => `/${segment}`).join('');
+  return `${prefix}${current.page}`;
+}

package/src/utils/search-content.ts

@@ -0,0 +1,12 @@
+/** Extracts the searchable prose from MDX in both builds and the runtime. */
+export function stripMdxToText(content: string): string {
+  return content
+    .replace(/^import\s+.*$/gm, '')
+    .replace(/^export\s+.*$/gm, '')
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/[#*_~`>|]/g, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/src/utils/theme.ts

@@ -5,7 +5,7 @@ const config = docsConfig as DoryConfig;
 
 export function loadTheme() {
   const root = document.documentElement;
-  const { theme, colors } = config;
+  const { theme } = config;
 
   // Apply forced dark/light mode
   if (theme?.mode === 'dark') {
@@ -20,10 +20,4 @@ export function loadTheme() {
   if (theme?.radius) {
     root.style.setProperty('--radius', theme.radius);
   }
-
-  // Mark as themed if custom background colors are provided
-  const hasCustomColors = colors?.background || colors?.surface || colors?.foreground;
-  if (hasCustomColors) {
-    root.setAttribute('data-dory-themed', 'true');
-  }
 }

package/vite.config.ssr.ts

@@ -1,9 +1,9 @@
 import { defineConfig } from 'vite';
 import preact from '@preact/preset-vite';
 import mdx from '@mdx-js/rollup';
-import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin';
-import { getMdxConfig } from './src/config/mdx';
-import { getBasePath, readDoryConfig } from './src/plugins/shared';
+import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin.ts';
+import { getMdxConfig } from './src/config/mdx.ts';
+import { getBasePath, readDoryConfig } from './src/plugins/shared.ts';
 
 // Minimal Vite config for the SSR build.
 // Only includes plugins needed for MDX compilation — no sitemap, prerender,

package/vite.config.ts

@@ -2,20 +2,21 @@ import { defineConfig } from 'vite';
 import preact from '@preact/preset-vite';
 import mdx from '@mdx-js/rollup';
 import tailwindcss from '@tailwindcss/vite'
-import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin';
-import { llmTxtGenerator } from './src/plugins/llm-txt-generator';
-import { llmTxtDevServer } from './src/plugins/llm-txt-dev-server';
-import { frontmatterGenerator } from './src/plugins/frontmatter-generator';
-import { frontmatterDevServer } from './src/plugins/frontmatter-dev-server';
-import { docsAssetsPlugin } from './src/plugins/docs-assets';
-import { htmlMetadataInjector } from './src/plugins/html-metadata-injector';
-import { htmlFilesMiddleware } from './src/plugins/html-files-middleware';
-import { analyticsInjector } from './src/plugins/analytics-injector';
-import { sitemapGenerator } from './src/plugins/sitemap-generator';
-import { robotsGenerator } from './src/plugins/robots-generator';
-import { prerender } from './src/plugins/prerender';
-import { getMdxConfig } from './src/config/mdx';
-import { getBasePath, readDoryConfig } from './src/plugins/shared';
+import { unifiedMdxPreprocessor } from './src/plugins/unified-mdx-plugin.ts';
+import { llmTxtGenerator } from './src/plugins/llm-txt-generator.ts';
+import { llmTxtDevServer } from './src/plugins/llm-txt-dev-server.ts';
+import { frontmatterGenerator } from './src/plugins/frontmatter-generator.ts';
+import { frontmatterDevServer } from './src/plugins/frontmatter-dev-server.ts';
+import { docsAssetsPlugin } from './src/plugins/docs-assets.ts';
+import { htmlMetadataInjector } from './src/plugins/html-metadata-injector.ts';
+import { htmlFilesMiddleware } from './src/plugins/html-files-middleware.ts';
+import { analyticsInjector } from './src/plugins/analytics-injector.ts';
+import { sitemapGenerator } from './src/plugins/sitemap-generator.ts';
+import { robotsGenerator } from './src/plugins/robots-generator.ts';
+import { prerender } from './src/plugins/prerender.ts';
+import { chatDevServer } from './src/plugins/chat-dev-server.ts';
+import { getMdxConfig } from './src/config/mdx.ts';
+import { getBasePath, readDoryConfig } from './src/plugins/shared.ts';
 
 export default defineConfig(({ command }) => ({
   // Serve and build under `basePath` from dory.json (asset URLs, import.meta.env.BASE_URL).
@@ -23,6 +24,7 @@ export default defineConfig(({ command }) => ({
   plugins: [
     // SINGLE SOURCE OF TRUTH: All MDX preprocessing happens in src/mdx/processor.ts
     htmlFilesMiddleware(), // Must be first to intercept HTML file requests
+    chatDevServer(),
     unifiedMdxPreprocessor(),
     preact(),
     mdx(getMdxConfig(command === 'serve')),
@@ -45,6 +47,11 @@ export default defineConfig(({ command }) => ({
       'react-dom': 'preact/compat',
     }
   },
+  // Mermaid is loaded on demand; prebundle it at startup so opening a diagram
+  // does not trigger a late dependency-cache rebuild and stale module URL.
+  optimizeDeps: {
+    include: ['mermaid'],
+  },
   publicDir: false, // Don't use a public directory since we need to import from docs
   build: {
     rollupOptions: {
@@ -54,7 +61,6 @@ export default defineConfig(({ command }) => ({
           if (!id.includes('node_modules')) return;
           if (/node_modules\/preact($|\/)/.test(id)) return 'vendor-preact';
           if (id.includes('node_modules/@clidey/ux') || id.includes('node_modules/@headlessui/react')) return 'vendor-ui';
-          if (id.includes('node_modules/lucide-react')) return 'vendor-icons';
           if (id.includes('node_modules/katex')) return 'katex';
           if (id.includes('node_modules/flexsearch')) return 'flexsearch';
         }