@clidey/dory 1.0.8 → 1.9.0

package/src/embedded-runtime/runtime.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en" class="dark">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; connect-src 'none'; img-src https: data: blob:; font-src 'self' data:; base-uri 'none'; form-action 'none'">
+  <title>Dory documentation</title>
+  <link rel="stylesheet" href="./dory-runtime.css">
+</head>
+<body style="margin:0;min-height:100vh">
+  <div id="dory-root"></div>
+  <script src="./dory-runtime.js"></script>
+</body>
+</html>

package/src/entry-server.tsx

@@ -2,26 +2,34 @@ import type { ComponentType } from 'preact';
 import { renderToString } from 'preact-render-to-string';
 import { Router } from 'wouter-preact';
 import { MDXProvider } from '@mdx-js/preact';
-import { ThemeProvider } from '@clidey/ux';
+import { ThemeProvider, Toaster } from '@clidey/ux';
 import * as mdxComponents from './mdx/mdx';
 import docsConfig from '../docs/dory.json' with { type: 'json' };
 import type { DoryConfig } from './types/config';
 import { PageMeta } from './ui/page-meta';
-import { BASE_PATH, assetUrl, withBase } from './utils/base-path';
+import { Header } from './ui/header';
+import { Navigation } from './components/navigation';
+import { Breadcrumb } from './ui/breadcrumb';
+import { PageFeedback } from './ui/page-feedback';
+import { PageFooter } from './ui/page-footer';
+import { PrevNextLinks } from './ui/prev-next-link';
+import { TableOfContents } from './ui/table-of-content';
+import { BASE_PATH, withBase } from './utils/base-path';
+import { contentScope } from './utils/content-scope';
 
 const config = docsConfig as DoryConfig;
 
-const navigationTabs = config.navigation?.tabs ?? [];
 if (!config.navigation?.tabs) {
   console.warn('dory.json has no navigation.tabs — SSR navigation will be empty.');
 }
 
 function pathFromFilename(filename: string): string {
-  return filename
+  const path = filename
     .replace(/^.*?docs/, '')
     .replace(/\/?index\.mdx$/, '/')
     .replace(/\.mdx$/, '')
     .toLowerCase();
+  return path.length > 1 ? path.replace(/\/$/, '') : path;
 }
 
 const pages = import.meta.glob('../docs/**/*.mdx');
@@ -44,19 +52,21 @@ interface NavTab {
   groups: NavGroup[];
 }
 
-function buildNavigation(frontmatter?: Record<string, any>[]): NavTab[] {
-  return navigationTabs.map(tab => ({
+function buildNavigation(routePath: string, frontmatter?: Record<string, any>[]): NavTab[] {
+  const scope = contentScope(config, routePath);
+  return scope.navigation.tabs.map(tab => ({
     title: tab.tab,
     groups: tab.groups.map(group => ({
       title: group.group,
-      pages: group.pages.map(page => {
-        const href = `/${page}`;
+      pages: group.pages.map(entry => {
+        const page = typeof entry === 'string' ? entry : entry.page;
+        const href = `${scope.prefix}/${page}`;
         const fm = frontmatter?.find(f => f.path === href);
         return {
           title: fm?.title || page.charAt(0).toUpperCase() + page.slice(1).replace(/-/g, ' '),
           href,
         };
-      })
+      }).filter(page => !scope.prefix || Boolean(allPages[page.href]))
     }))
   }));
 }
@@ -69,7 +79,7 @@ export async function render(routePath: string, frontmatter?: Record<string, any
     const module = await loader() as { default: ComponentType };
     const Content = module.default;
 
-    const navigation = buildNavigation(frontmatter);
+    const navigation = buildNavigation(routePath, frontmatter);
     const pageFm = frontmatter?.find(fm => fm.path === routePath);
 
     // Find group/page titles (Layout uses swapped names: "title: group, group: title")
@@ -87,107 +97,35 @@ export async function render(routePath: string, frontmatter?: Record<string, any
       }
     }
 
-    // Prev/next
-    const allLinks = navigation.flatMap(tab =>
-      tab.groups.flatMap(group => group.pages)
-    );
-    const linkIndex = allLinks.findIndex(link => link.href === routePath);
-    const prevPage = linkIndex > 0 ? allLinks[linkIndex - 1] : null;
-    const nextPage = linkIndex < allLinks.length - 1 ? allLinks[linkIndex + 1] : null;
+    const isOpenAPIPage = Boolean(pageFm?.openapi);
 
     return renderToString(
       <ThemeProvider>
+        <Toaster />
         <Router base={BASE_PATH} ssrPath={withBase(routePath)}>
           <MDXProvider components={mdxComponents}>
-                <div class="flex w-full flex-col">
-                  {/* SYNC NOTE: the static shell below (header chrome, sidebar nav skeleton,
-                       main/article wrappers) hand-mirrors the client components:
-                       - <header> block  -> src/ui/header.tsx (Header component JSX)
-                       - #container/nav  -> src/ui/layout.tsx (non-landing return) + src/components/navigation.tsx
-                       When editing structure or classes in either place, update the counterpart,
-                       or hydration will mismatch. Client-only widgets (Search, ModeToggle,
-                       MobileNav) are intentionally NOT rendered here — see placeholder below. */}
-                  {/* Header — matches src/ui/header.tsx structure */}
-                  <header class="sticky top-0 z-50 flex flex-none flex-wrap items-center justify-between bg-white px-4 py-5 shadow-md shadow-gray-900/5 sm:px-6 lg:px-8 dark:shadow-none dark:bg-transparent">
-                    <div class="relative flex justify-between gap-6 sm:gap-8 md:grow items-center w-full px-4">
-                      <div class="flex items-center grow gap-2">
-                        {config.logo && (
-                          <>
-                            <img src={assetUrl(config.logo.light)} alt="logo" class="w-8 hidden dark:block" />
-                            <img src={assetUrl(config.logo.dark)} alt="logo" class="w-8 block dark:hidden" />
-                          </>
-                        )}
-                        <h1 class="text-base lg:text-2xl font-bold">{config.name}</h1>
-                      </div>
-                      <nav class="hidden md:block">
-                        <ul role="list" class="flex items-center gap-8">
-                          {navigation.map(tab => {
-                            const isActive = tab === currentTab;
-                            return (
-                              <li key={tab.title}>
-                                <a
-                                  href={withBase(tab.groups[0].pages[0].href)}
-                                  class={`text-xs transition hover:opacity-80${isActive ? ' text-brand-foreground' : ''}`}
-                                >
-                                  {tab.title}
-                                </a>
-                              </li>
-                            );
-                          })}
-                        </ul>
-                      </nav>
-                      <div class="hidden md:block md:h-5 md:w-px md:bg-zinc-900/10 md:dark:bg-white/15" />
-                      {/* Search, ModeToggle, MobileNav — rendered client-side during hydration.
-                           Static placeholders cause ref mismatches with Algolia autocomplete. */}
-                      <div class="flex items-center gap-3" data-testid="header-actions" />
-                    </div>
-                  </header>
-
-                  {/* Container — matches src/ui/layout.tsx structure */}
-                  <div id="container" class="relative flex w-full max-w-8xl sm:px-2 lg:px-8">
-                    <div class="hidden lg:relative lg:block lg:flex-none">
-                      <div class="sticky top-[4.75rem] -ml-0.5 h-[calc(100vh-4.75rem)] w-64 overflow-x-hidden overflow-y-auto py-16 pr-8 pl-0.5 xl:w-72 xl:pr-16">
-                        <nav class="dory-navigation text-base lg:text-sm">
-                          <ul role="list" class="space-y-9">
-                            {currentTab && (
-                              <li>
-                                <h2 class="font-display font-medium text-xs">{currentTab.title}</h2>
-                                {currentTab.groups.map(group => (
-                                  <div key={group.title}>
-                                    <h3 class="mt-4 text-sm font-semibold">{group.title}</h3>
-                                    <ul role="list" class="mt-2 space-y-2 border-l-2 border-border lg:mt-4 lg:space-y-4 lg:border-border">
-                                      {group.pages.map(page => (
-                                        <li key={page.href} class="relative">
-                                          <a
-                                            href={withBase(page.href)}
-                                            class={routePath === page.href
-                                              ? 'block w-full pl-3.5 font-semibold text-brand-foreground before:pointer-events-none before:absolute before:top-1/2 before:-left-1 before:h-1.5 before:w-1.5 before:-translate-y-1/2 before:rounded-full'
-                                              : 'block w-full pl-3.5 text-muted-foreground before:hidden before:bg-slate-300 hover:text-muted-foreground hover:before:block dark:text-muted-foreground dark:before:bg-slate-700 dark:hover:text-slate-300 before:pointer-events-none before:absolute before:top-1/2 before:-left-1 before:h-1.5 before:w-1.5 before:-translate-y-1/2 before:rounded-full'}
-                                          >
-                                            {page.title}
-                                          </a>
-                                        </li>
-                                      ))}
-                                    </ul>
-                                  </div>
-                                ))}
-                              </li>
-                            )}
-                          </ul>
-                        </nav>
+                {/* SYNC NOTE: this shell mirrors src/ui/layout.tsx (non-landing return).
+                     Header and Navigation are the real components; Header gets `ssr` so the
+                     client-only widgets (search, theme toggle, mobile menu) mount on hydration. */}
+                <div class="dory-shell flex min-h-screen w-full flex-col bg-[var(--sidebar)]">
+                  <Header ssr />
+                  <div class="flex flex-1">
+                    <aside class="hidden w-60 shrink-0 lg:block">
+                      <div class="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto px-3 pb-6 pt-4">
+                        <Navigation frontmatter={frontmatter} />
                       </div>
-                    </div>
-
-                    <main class="flex grow max-w-full px-4 py-16 sm:px-6 lg:px-8">
-                      <div class="min-w-0 w-full">
-                        <article class="h-full flex flex-1 flex-col">
-                          <div class="flex justify-between items-start">
-                            <header class="mb-8">
-                              {groupTitle && <h1 class="font-display text-lg tracking-tight">{groupTitle}</h1>}
-                              {pageFm?.title && <p class="text-4xl tracking-tight">{pageFm.title}</p>}
-                              {pageFm?.lead && <p class="dory-lead">{pageFm.lead}</p>}
-                            </header>
+                    </aside>
+                    <main class="dory-main min-w-0 flex-1 bg-background text-foreground px-6 py-10 sm:px-10 lg:px-12">
+                      <div class="mx-auto flex w-full max-w-[66rem] justify-center gap-14">
+                        <article class={`dory-article flex min-w-0 flex-1 flex-col ${isOpenAPIPage ? 'max-w-[66rem]' : 'max-w-[47rem]'}`}>
+                          {/* Page actions (Copy page / AI actions) are client-only and mount on hydration. */}
+                          <div class="mb-6 flex min-h-9 flex-wrap items-center justify-between gap-4">
+                            <Breadcrumb group={groupTitle} title={pageFm?.title} />
                           </div>
+                          <header class="mb-10">
+                            {pageFm?.title && <h1 class="dory-page-title">{pageFm.title}</h1>}
+                            {pageFm?.lead && <p class="dory-lead">{pageFm.lead}</p>}
+                          </header>
                           <PageMeta meta={pageFm?.meta} />
                           <div class="flex-1 min-h-[calc(100vh-2rem)]">
                             {/* Matches App > div.antialiased > div.flex > Routes > Content */}
@@ -197,27 +135,11 @@ export async function render(routePath: string, frontmatter?: Record<string, any
                               </div>
                             </div>
                           </div>
-                          {(prevPage || nextPage) && (
-                            <div class="mt-12 pt-6 flex border-t border-black/20 dark:border-white/20">
-                              {prevPage && (
-                                <div>
-                                  <p class="font-display text-sm font-medium">Previous</p>
-                                  <div class="mt-1">
-                                    <a href={withBase(prevPage.href)} class="text-base font-semibold hover:opacity-80">{prevPage.title}</a>
-                                  </div>
-                                </div>
-                              )}
-                              {nextPage && (
-                                <div class="ml-auto text-right">
-                                  <p class="font-display text-sm font-medium">Next</p>
-                                  <div class="mt-1">
-                                    <a href={withBase(nextPage.href)} class="text-base font-semibold hover:opacity-80">{nextPage.title}</a>
-                                  </div>
-                                </div>
-                              )}
-                            </div>
-                          )}
+                          <PageFeedback pathname={routePath} />
+                          <PrevNextLinks navigation={navigation} />
+                          <PageFooter />
                         </article>
+                        {!isOpenAPIPage && <TableOfContents />}
                       </div>
                     </main>
                   </div>

package/src/main.tsx

@@ -2,6 +2,7 @@ import { render, hydrate } from 'preact'
 import { Router } from 'wouter-preact'
 import '@clidey/ux/styles.css';
 import '@clidey/ux/brand.css';
+import '@clidey/ux/theme-fonts.css';
 import { App } from './app.tsx'
 import { withMDX } from './components/mdx-provider.tsx'
 import { ErrorBoundary } from './components/error-boundary.tsx'
@@ -13,7 +14,7 @@ import { ThemeProvider } from '@clidey/ux'
 import { preloadFrontmatter } from './components/store'
 import docsConfig from '../docs/dory.json' with { type: 'json' };
 import type { DoryConfig } from './types/config';
-import { BASE_PATH } from './utils/base-path';
+import { BASE_PATH, withBase } from './utils/base-path';
 
 const config = docsConfig as DoryConfig;
 
@@ -29,11 +30,19 @@ const AppWithMDX = withMDX(App)
 
 const appRoot = document.getElementById('app')!
 const hasSSRContent = appRoot.children.length > 0
+const currentPath = window.location.pathname.replace(/\/$/, '') || '/'
+const renderedPath = window.__DORY_ROUTE__ ? withBase(window.__DORY_ROUTE__).replace(/\/$/, '') || '/' : undefined
+const rootPath = withBase('/').replace(/\/$/, '') || '/'
+const canHydrate = hasSSRContent && (!renderedPath || currentPath === renderedPath || currentPath === rootPath)
 
-const defaultTheme = config.theme?.mode === 'dark' ? 'dark' : config.theme?.mode === 'light' ? 'light' : 'system';
+const embedParams = new URLSearchParams(window.location.search);
+const requestedTheme = embedParams.get('embedded') === 'true' ? embedParams.get('theme') : null;
+const embedTheme = requestedTheme === 'dark' || requestedTheme === 'light' ? requestedTheme : null;
+const defaultTheme = embedTheme ?? (config.theme?.mode === 'dark' ? 'dark' : config.theme?.mode === 'light' ? 'light' : 'system');
+if (embedTheme) document.documentElement.style.colorScheme = embedTheme;
 
 const tree = (
-    <ThemeProvider defaultTheme={defaultTheme} storageKey="@clidey/dory/theme">
+    <ThemeProvider defaultTheme={defaultTheme} storageKey={embedTheme ? `@clidey/dory/embed-theme-${embedTheme}` : '@clidey/dory/theme'}>
         <Toaster />
         <ErrorBoundary>
             <Router base={BASE_PATH}>
@@ -45,8 +54,11 @@ const tree = (
 
 // If SSR content exists, hydrate (attach JS to existing DOM).
 // Otherwise, render from scratch (dev mode, non-SSR pages).
-if (hasSSRContent) {
+if (canHydrate) {
     hydrate(tree, appRoot)
 } else {
+    // A static host may serve the prerendered index.html for an unknown URL.
+    // Its first-page markup cannot hydrate into the 404 view.
+    if (hasSSRContent) appRoot.replaceChildren()
     render(tree, appRoot)
 }

package/src/mdx/accordion.tsx

@@ -1,11 +1,11 @@
-import {
+import { CatalogIcon,
   Accordion as UXAccordion,
   AccordionItem,
   AccordionTrigger,
   AccordionContent
 } from '@clidey/ux'
 import classNames from 'classnames'
-import { Plus } from 'lucide-react'
+
 import { Icon } from './icon'
 
 export function AccordionGroup({ children, numbered = false }: { children: React.ReactNode; numbered?: boolean }) {
@@ -32,7 +32,7 @@ export function Accordion({
           {icon && <Icon icon={icon} className="h-3.5 w-3.5 !stroke-[var(--primary)] text-[var(--primary)]" />}
           <span className="text-sm font-semibold">{title}</span>
         </div>
-        <Plus aria-hidden="true" className="size-3.5 shrink-0 text-muted-foreground transition-transform duration-200 group-data-[state=open]:rotate-45" />
+        <CatalogIcon name="plus" aria-hidden="true" className="size-3.5 shrink-0 text-muted-foreground transition-transform duration-200 group-data-[state=open]:rotate-45" />
       </AccordionTrigger>
       <AccordionContent>
         <div className="px-4 pb-3 leading-relaxed text-muted-foreground">

package/src/mdx/api-playground.tsx

@@ -1,8 +1,11 @@
-import { Button, TextArea, useTheme, Input } from '@clidey/ux'
+import { CatalogIcon, Button, TextArea, useTheme, Input as UxInput } from '@clidey/ux'
+
+// The ux Input is typed against React's input props, which Preact 11's compat types no longer expose.
+const Input = UxInput as unknown as (props: preact.JSX.IntrinsicElements['input']) => preact.JSX.Element
 import { Tab, TabGroup, TabList, TabPanel, TabPanels } from '@headlessui/react'
-import { CheckIcon } from '@heroicons/react/24/outline'
+
 import classNames from 'classnames'
-import { PencilIcon, PlusIcon, TrashIcon, XIcon } from 'lucide-react'
+
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
 import { Highlight, themes } from 'prism-react-renderer'
 import Dropdown from '../components/dropdown'
@@ -176,10 +179,10 @@ export const HeadersTab = ({ requestConfig, setRequestConfig }: HeadersTabProps)
                 className="flex-1 text-sm"
               />
               <Button onClick={() => saveHeader(idx)}>
-                <CheckIcon className="w-4 h-4" />
+                <CatalogIcon name="check" className="w-4 h-4" />
               </Button>
               <Button onClick={() => cancelEdit(idx)}>
-                <XIcon className="w-4 h-4" />
+                <CatalogIcon name="close" className="w-4 h-4" />
               </Button>
             </>
           ) : (
@@ -187,17 +190,17 @@ export const HeadersTab = ({ requestConfig, setRequestConfig }: HeadersTabProps)
               <span className="text-sm  w-32 truncate">{hdr.key}</span>
               <span className="text-sm  flex-1 truncate">{hdr.value}</span>
               <Button onClick={() => editHeader(idx)}>
-                <PencilIcon className="w-4 h-4" />
+                <CatalogIcon name="edit" className="w-4 h-4" />
               </Button>
               <Button onClick={() => removeHeader(idx)} className="text-red-400">
-                <TrashIcon className="w-4 h-4" />
+                <CatalogIcon name="trash" className="w-4 h-4" />
               </Button>
             </>
           )}
         </div>
       ))}
       <Button onClick={addEmptyHeaderRow} className="text-sm mt-2 w-fit">
-        <PlusIcon className="w-4 h-4" /> Add Header
+        <CatalogIcon name="plus" className="w-4 h-4" /> Add Header
       </Button>
     </div>
   )
@@ -284,10 +287,10 @@ export const ParamsTab = ({ queryParams, setQueryParams }: ParamsTabProps) => {
               <Input value={p.name} onChange={e => updateParam(i, 'name', (e.target as HTMLInputElement).value)} placeholder="Param name" className="w-32 text-sm" />
               <Input value={p.value} onChange={e => updateParam(i, 'value', (e.target as HTMLInputElement).value)} placeholder="Param value" className="flex-1 text-sm" />
               <Button onClick={() => saveParam(i)}>
-                <CheckIcon className="w-4 h-4" />
+                <CatalogIcon name="check" className="w-4 h-4" />
               </Button>
               <Button onClick={() => cancelEdit(i)}>
-                <XIcon className="w-4 h-4" />
+                <CatalogIcon name="close" className="w-4 h-4" />
               </Button>
             </>
           ) : (
@@ -295,23 +298,22 @@ export const ParamsTab = ({ queryParams, setQueryParams }: ParamsTabProps) => {
               <span className="w-32 truncate text-sm">{p.name}</span>
               <span className="flex-1 truncate text-sm">{p.value}</span>
               <Button onClick={() => editParam(i)}>
-                <PencilIcon className="w-4 h-4" />
+                <CatalogIcon name="edit" className="w-4 h-4" />
               </Button>
               <Button onClick={() => removeParam(i)} className="text-red-400">
-                <TrashIcon className="w-4 h-4" />
+                <CatalogIcon name="trash" className="w-4 h-4" />
               </Button>
             </>
           )}
         </div>
       ))}
       <Button onClick={addParamRow} className="mt-2 text-sm self-end">
-        <PlusIcon className="w-4 h-4" /> Add Parameter
+        <CatalogIcon name="plus" className="w-4 h-4" /> Add Parameter
       </Button>
     </div>
   );
 };
 
-
 export function APIPlayground({
   method,
   url,
@@ -596,7 +598,7 @@ export function APIPlayground({
         {/* Response */}
         <div className="flex-1">
           <div className="px-4 py-3">
-            <h3 className="text-sm font-semibold">Response</h3>
+            <h3 className="text-sm font-semibold" data-toc-ignore>Response</h3>
           </div>
           
           <div className="p-4">
@@ -659,4 +661,4 @@ export function APIPlayground({
       </div>
     </div>
   )
-}
+}

package/src/mdx/async-api.tsx

@@ -131,7 +131,7 @@ export function AsyncAPI({
 
   return (
     <div className="dory-asyncapi max-w-none w-full">
-      {(operation.description || operation.summary) && <p className="dory-lead -mt-4 mb-6">{operation.description || operation.summary}</p>}
+      {(operation.description || operation.summary) && <p className="dory-lead -mt-4! mb-6">{operation.description || operation.summary}</p>}
 
       <h2 id="connect" className="dory-h2 font-heading mb-3 mt-10"><span>Connect</span></h2>
       <WebSocketPanel url={channel.address ?? selectedChannel} servers={wsServers} headers={defaultHeaders} />
@@ -150,7 +150,7 @@ export function AsyncAPI({
             <tbody>
               {rows.map((row) => (
                 <tr key={`${row.direction}-${row.name}`}>
-                  <Td><span className="font-mono text-xs">{row.name}</span></Td>
+                  <Td><span className="font-mono text-[13px] text-foreground">{row.name}</span></Td>
                   <Td>
                     <span className={row.direction === 'SEND' ? 'font-mono text-xs font-semibold text-[var(--brand-readable,#b65401)]' : 'font-mono text-xs font-semibold text-[var(--primary)]'}>
                       {row.direction}

package/src/mdx/card.tsx

@@ -2,6 +2,7 @@ import classNames from "classnames";
 import { withBase } from '../utils/base-path';
 import { Icon } from "./icon";
 import type { ComponentChildren } from "preact";
+import { Card as UxCard } from '@clidey/ux';
 
 export function CardGroup({ children, cols = 2, numbered = false }: { children: React.ReactNode; cols?: number; numbered?: boolean }) {
   return (
@@ -31,7 +32,7 @@ export function Card({
   children?: ComponentChildren
 }) {
   return (
-    <div className="dory-card group relative flex flex-col rounded-lg border border-[var(--border)] bg-card p-4 transition-shadow hover:shadow-[0_2px_10px_rgb(14_34_64/0.07)]">
+    <UxCard className="dory-card group relative gap-0 rounded-lg border-[var(--border)] bg-card p-4 shadow-none transition-shadow hover:shadow-[0_2px_10px_rgb(14_34_64/0.07)]">
       {href && <a href={withBase(href)} className="absolute inset-0 z-10 rounded-lg" aria-label={title} />}
       {(icon || href) && (
         <div className="mb-3 flex items-start justify-between">
@@ -47,6 +48,6 @@ export function Card({
       <div className="mt-1 text-[13px] leading-normal text-muted-foreground [&_p]:mb-0">
         {description ?? children}
       </div>
-    </div>
+    </UxCard>
   )
 }

package/src/mdx/code.tsx

@@ -1,5 +1,5 @@
 import { Tab, TabGroup, TabList, TabPanel, TabPanels } from '@headlessui/react'
-import { ClipboardIcon } from '@heroicons/react/24/outline'
+
 import classNames from 'classnames'
 import {
   Children,
@@ -8,12 +8,13 @@ import {
   useEffect,
   useState
 } from 'react'
-import { File, SquareTerminal } from 'lucide-react'
+
 import { Tag } from './tag'
 import { diffBaseLanguage, isTerminalSession, parseFenceMeta, type FenceMeta } from './fence-meta'
 import { toTitleCase } from '../utils/functions'
-import { Button } from '@clidey/ux'
-import { CheckIcon } from 'lucide-react'
+import { CatalogIcon, Button } from '@clidey/ux'
+
+import { captureDocsEvent } from '../utils/analytics'
 
 export const supportedLanguages = {
   'python': 'Python',
@@ -87,7 +88,7 @@ function languageName(language: string) {
   return supportedLanguages[language as keyof typeof supportedLanguages] || toTitleCase(language)
 }
 
-function CopyButton({ code }: { code: string }) {
+export function CopyButton({ code }: { code: string }) {
   const [copyCount, setCopyCount] = useState(0)
   const copied = copyCount > 0
 
@@ -111,6 +112,7 @@ function CopyButton({ code }: { code: string }) {
       onClick={() => {
         window.navigator.clipboard.writeText(code).then(() => {
           setCopyCount((count) => count + 1)
+          captureDocsEvent('docs_code_copied', { path: window.location.pathname })
         })
       }}
     >
@@ -121,7 +123,7 @@ function CopyButton({ code }: { code: string }) {
           copied && '-translate-y-1.5 opacity-0',
         )}
       >
-        <ClipboardIcon className="h-3.5 w-3.5 stroke-muted-foreground transition-colors group-hover/button:stroke-foreground" />
+        <CatalogIcon name="clipboard" className="h-3.5 w-3.5 stroke-muted-foreground transition-colors group-hover/button:stroke-foreground" />
       </span>
       <span
         aria-hidden={!copied}
@@ -130,7 +132,7 @@ function CopyButton({ code }: { code: string }) {
           !copied && 'translate-y-1.5 opacity-0',
         )}
       >
-        <CheckIcon className="h-3.5 w-3.5" />
+        <CatalogIcon name="check" className="h-3.5 w-3.5" />
       </span>
     </Button>
   )
@@ -161,8 +163,8 @@ export function FenceHeader({ language, code, meta }: FenceProps) {
   return (
     <div className="flex min-h-10 items-center gap-2 border-b border-[var(--border)] bg-muted pl-4 pr-12">
       {terminal
-        ? <SquareTerminal aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
-        : meta.title && <File aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />}
+        ? <CatalogIcon name="terminal" aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+        : meta.title && <CatalogIcon name="file" aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />}
       <p className="mr-auto truncate font-mono text-xs font-medium text-foreground">{title}</p>
       {diff && (
         <span className="font-mono text-xs">

package/src/mdx/fence.tsx

@@ -8,13 +8,14 @@ import classNames from 'classnames'
 
 // Colors resolve through CSS variables so one theme serves both light and dark mode.
 const codeTheme: PrismTheme = {
-  plain: { color: 'var(--foreground)', backgroundColor: 'transparent' },
+  plain: { color: 'var(--syntax-plain)', backgroundColor: 'transparent' },
   styles: [
-    { types: ['comment', 'prolog', 'doctype', 'cdata'], style: { color: 'var(--muted-foreground)', fontStyle: 'italic' } },
-    { types: ['keyword', 'builtin', 'function', 'tag', 'selector', 'number', 'boolean', 'constant', 'property', 'class-name'], style: { color: 'var(--primary)' } },
-    { types: ['string', 'char', 'attr-value', 'url', 'regex', 'inserted'], style: { color: 'var(--dory-code-string)' } },
+    { types: ['comment', 'prolog', 'doctype', 'cdata'], style: { color: 'var(--syntax-comment)', fontStyle: 'italic' } },
+    { types: ['keyword', 'builtin', 'function', 'tag', 'selector', 'property', 'class-name'], style: { color: 'var(--syntax-keyword)' } },
+    { types: ['number', 'boolean', 'constant'], style: { color: 'var(--syntax-number)' } },
+    { types: ['string', 'char', 'attr-value', 'url', 'regex', 'inserted'], style: { color: 'var(--syntax-string)' } },
     { types: ['deleted'], style: { color: 'var(--destructive)' } },
-    { types: ['punctuation', 'operator'], style: { color: 'var(--foreground)' } },
+    { types: ['punctuation', 'operator'], style: { color: 'var(--syntax-plain)' } },
   ],
 }
 

package/src/mdx/icon-grid.tsx

@@ -1,8 +1,11 @@
 import { useNotification } from '../components/notification'
 import { Icon } from './icon'
+import { icons as catalog } from '@clidey/ux/icons'
+
+const iconNames = Object.keys(catalog).sort()
 
 /** Grid of icon tiles. Clicking a tile copies its `<Icon icon="…" />` tag. */
-export function IconGrid({ icons, cols = 4 }: { icons: string[]; cols?: number }) {
+export function IconGrid({ icons = iconNames, cols = 4 }: { icons?: string[]; cols?: number }) {
   const { showNotification } = useNotification()
 
   const copy = (name: string) => {

package/src/mdx/icon-names.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+import { resolveIconName } from './icon-names'
+
+describe('MDX icon name compatibility', () => {
+  it('keeps source-prefixed variants distinct from the default icon', () => {
+    expect(resolveIconName('chevron-down')).toBe('chevron-down')
+    expect(resolveIconName('enterprise/chevron-down')).toBe('chevron-down-alt-2')
+  })
+
+  it('preserves legacy document names', () => {
+    expect(resolveIconName('Search')).toBe('search')
+    expect(resolveIconName('alert-triangle')).toBe('warning')
+    expect(resolveIconName('sparkles')).toBe('ai')
+  })
+})