@clidey/dory 0.46.0 → 0.48.0

package/src/entry-server.tsx

@@ -1,7 +1,18 @@
-import {renderToString} from 'preact-render-to-string';
-import {Router} from 'wouter-preact';
-import {MDXProvider} from '@mdx-js/preact';
+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 * as mdxComponents from './mdx/mdx';
+import docsConfig from '../docs/dory.json' with { type: 'json' };
+import type { DoryConfig } from './types/config';
+
+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
@@ -16,88 +27,200 @@ const allPages = Object.fromEntries(
   Object.entries(pages).map(([path, loader]) => [pathFromFilename(path), loader])
 );
 
-// SSR-safe Pre: renders code blocks without syntax highlighting.
-// The client-side Fence component uses useTheme() from @clidey/ux which
-// requires ThemeProvider (localStorage access). Plain pre/code is sufficient
-// for crawlers — syntax highlighting is a visual enhancement.
-function SSRPre(props: any) {
-  const child = props.children?.props;
-  const className = child?.className || '';
-  const code = child?.children || '';
-  return (
-    <pre class="overflow-x-auto p-4 text-xs">
-      <code class={className}>{code}</code>
-    </pre>
-  );
+interface NavPage {
+  title: string;
+  href: string;
 }
 
-// SSR-safe Latex: renders the raw expression as text.
-// The client-side Latex component lazy-loads KaTeX in useEffect.
-function SSRLatex({ children }: { children: any }) {
-  return (
-    <div class="my-4">
-      <code>{children}</code>
-    </div>
-  );
+interface NavGroup {
+  title: string;
+  pages: NavPage[];
 }
 
-// SSR-safe table: @clidey/ux's Table component renders a vaul Drawer
-// (Preview drawer) alongside every table. vaul's useScaleBackground
-// accesses document.body at render time, crashing in Node.js.
-function SSRTable(props: any) {
-  return (
-    <div class="overflow-x-auto rounded-lg my-8">
-      <table class="table-auto border-collapse min-w-full" {...props} />
-    </div>
-  );
-}
-function SSRTh(props: any) {
-  return <th class="px-4 py-2 text-left text-sm font-medium" {...props} />;
-}
-function SSRTd(props: any) {
-  return <td class="px-4 py-2 text-sm" {...props} />;
+interface NavTab {
+  title: string;
+  groups: NavGroup[];
 }
 
-// SSR-safe placeholders for interactive components that use Suspense/lazy.
-// renderToString cannot handle Suspense boundaries — these components are
-// interactive-only anyway (playgrounds, diagrams) and not meaningful for crawlers.
-function SSRPlaceholder() {
-  return null;
+function buildNavigation(frontmatter?: Record<string, any>[]): NavTab[] {
+  return navigationTabs.map(tab => ({
+    title: tab.tab,
+    groups: tab.groups.map(group => ({
+      title: group.group,
+      pages: group.pages.map(page => {
+        const href = `/${page}`;
+        const fm = frontmatter?.find(f => f.path === href);
+        return {
+          title: fm?.title || page.charAt(0).toUpperCase() + page.slice(1).replace(/-/g, ' '),
+          href,
+        };
+      })
+    }))
+  }));
 }
 
-const ssrComponents: Record<string, any> = {
-  ...mdxComponents,
-  pre: SSRPre,
-  Latex: SSRLatex,
-  table: SSRTable,
-  th: SSRTh,
-  td: SSRTd,
-  APIPlayground: SSRPlaceholder,
-  WebSocketPlayground: SSRPlaceholder,
-};
-
-export async function render(routePath: string): Promise<string> {
+export async function render(routePath: string, frontmatter?: Record<string, any>[]): Promise<string> {
   const loader = allPages[routePath];
   if (!loader) return '';
 
   try {
-    const module = await loader() as any;
+    const module = await loader() as { default: ComponentType };
     const Content = module.default;
 
+    const navigation = buildNavigation(frontmatter);
+    const pageFm = frontmatter?.find(fm => fm.path === routePath);
+
+    // Find group/page titles (Layout uses swapped names: "title: group, group: title")
+    let groupTitle = '';
+    const currentTab = navigation.find(tab =>
+      tab.groups.some(group =>
+        group.pages.some(page => page.href === routePath)
+      )
+    );
+    if (currentTab) {
+      for (const group of currentTab.groups) {
+        if (group.pages.some(p => p.href === routePath)) {
+          groupTitle = group.title;
+        }
+      }
+    }
+
+    // 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;
+
     return renderToString(
+      <ThemeProvider>
         <Router ssrPath={routePath}>
-          <MDXProvider components={ssrComponents}>
-            <div class="flex w-full flex-col">
-              <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">
-                    <Content/>
-                  </article>
+          <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={`/${config.logo.light}`} alt="logo" class="w-8 hidden dark:block" />
+                            <img src={`/${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={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-slate-100 lg:mt-4 lg:space-y-4 lg:border-slate-200 dark:border-slate-800">
+                                      {group.pages.map(page => (
+                                        <li key={page.href} class="relative">
+                                          <a
+                                            href={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-slate-500 before:hidden before:bg-slate-300 hover:text-slate-600 hover:before:block dark:text-slate-400 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>
+                      </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>}
+                            </header>
+                          </div>
+                          <div class="flex-1 min-h-[calc(100vh-2rem)]">
+                            {/* Matches App > div.antialiased > div.flex > Routes > Content */}
+                            <div class="h-full antialiased">
+                              <div class="flex min-h-full">
+                                <Content />
+                              </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={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={nextPage.href} class="text-base font-semibold hover:opacity-80">{nextPage.title}</a>
+                                  </div>
+                                </div>
+                              )}
+                            </div>
+                          )}
+                        </article>
+                      </div>
+                    </main>
+                  </div>
                 </div>
-              </main>
-            </div>
           </MDXProvider>
         </Router>
+      </ThemeProvider>
     );
   } catch (error) {
     console.warn(`SSR render failed for ${routePath}:`, error);

package/src/main.tsx

@@ -1,25 +1,47 @@
-import { render } from 'preact'
+import { render, hydrate } from 'preact'
 import '@clidey/ux/styles.css';
 import { App } from './app.tsx'
 import { withMDX } from './components/mdx-provider.tsx'
 import { ErrorBoundary } from './components/error-boundary.tsx'
 import { loadFonts } from './utils/fonts'
 import { loadColors } from './utils/colors'
+import { loadTheme } from './utils/theme'
 import { Toaster } from '@clidey/ux'
 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';
+
+const config = docsConfig as DoryConfig;
+
+// Start frontmatter loading immediately — if inlined from SSR, this is a no-op.
+preloadFrontmatter()
 
 // Load fonts and colors before rendering the app
 loadFonts()
 loadColors()
+loadTheme()
 
 const AppWithMDX = withMDX(App)
 
-render(
-    <ThemeProvider storageKey="@clidey/dory/theme">
+const appRoot = document.getElementById('app')!
+const hasSSRContent = appRoot.children.length > 0
+
+const defaultTheme = config.theme?.mode === 'dark' ? 'dark' : config.theme?.mode === 'light' ? 'light' : 'system';
+
+const tree = (
+    <ThemeProvider defaultTheme={defaultTheme} storageKey="@clidey/dory/theme">
         <Toaster />
         <ErrorBoundary>
             <AppWithMDX />
         </ErrorBoundary>
-    </ThemeProvider>,
-    document.getElementById('app')!
+    </ThemeProvider>
 )
+
+// If SSR content exists, hydrate (attach JS to existing DOM).
+// Otherwise, render from scratch (dev mode, non-SSR pages).
+if (hasSSRContent) {
+    hydrate(tree, appRoot)
+} else {
+    render(tree, appRoot)
+}

package/src/mdx/api-playground.tsx

@@ -323,6 +323,8 @@ export function APIPlayground({
   authType = 'none',
   servers = []
 }: APIPlaygroundProps) {
+  if (typeof window === 'undefined') return null
+
   const [selectedTab, setSelectedTab] = useState(0)
   const [isLoading, setIsLoading] = useState(false)
   const [response, setResponse] = useState<ResponseData | null>(null)

package/src/mdx/code.tsx

@@ -115,7 +115,7 @@ function CodePanelHeader({ tag, label }: { tag?: string; label?: string }) {
   if (!tag && !label) return null
 
   return (
-    <div className="flex h-9 items-center gap-2 border-y border-t-transparent border-b-white/7.5 bg-white/2.5 px-4 dark:border-b-white/5 dark:bg-white/1">
+    <div className="flex h-9 items-center gap-2 border-b border-t-transparent px-4" style={{ borderColor: 'var(--border)' }}>
       {tag && (
         <div className="dark flex">
           <Tag variant="small">{tag}</Tag>
@@ -155,7 +155,7 @@ function CodePanel({
   }
 
   return (
-    <div className="group dark:bg-white/2.5">
+    <div className="group">
       <CodePanelHeader tag={tag} label={label} />
       <div className="relative">
         <pre className="overflow-x-auto p-4 text-xs">{children}</pre>
@@ -257,7 +257,7 @@ export function CodeGroup({
   return (
     <CodeGroupContext.Provider value={true}>
       {hasTabs ? (
-        <Card className="py-0 border-black/10 bg-none overflow-hidden mb-4">
+        <Card className="p-0 border-black/10 bg-none overflow-hidden mb-4">
           <TabGroup
             as="div"
             selectedIndex={selectedIndex}
@@ -270,7 +270,7 @@ export function CodeGroup({
           </TabGroup>
         </Card>
       ) : (
-        <Card className="py-0 border-black/10 bg-none overflow-hidden mb-4">
+        <Card className="p-0 border-black/10 bg-none overflow-hidden mb-4">
           <div className="not-prose">
             {header}
             {panels}
@@ -285,5 +285,8 @@ export function Code({
   children,
   ...props
 }: React.ComponentPropsWithoutRef<'code'>) {
-  return <code className={classNames('dory-mdx-code rounded-md py-1 text-sm px-2', props.className)} {...props}>{children}</code>
+  const isBlock = typeof props.className === 'string' && props.className.includes('language-');
+  return <code className={classNames(props.className, {
+    'dory-mdx-code rounded-md py-0.5 text-sm px-1.5': !isBlock,
+  })} {...props}>{children}</code>
 }

package/src/mdx/fence.tsx

@@ -6,6 +6,14 @@ import { Loading } from '../components/loading'
 import { useTheme } from '@clidey/ux'
 import classNames from 'classnames'
 
+function dedent(code: string): string {
+  const lines = code.replace(/^\n+/, '').replace(/\s+$/, '').split('\n');
+  const indents = lines.filter(l => l.trim().length > 0).map(l => l.match(/^(\s*)/)?.[1].length ?? 0);
+  const minIndent = indents.length > 0 ? Math.min(...indents) : 0;
+  if (minIndent === 0) return lines.join('\n');
+  return lines.map(l => l.slice(minIndent)).join('\n');
+}
+
 
 export function Fence({
   children,
@@ -31,12 +39,12 @@ export function Fence({
 
   return (
     <Highlight
-      code={children.trimEnd()}
+      code={dedent(children)}
       language={supportedLanguage}
       theme={isDark ? themes.vsDark : themes.vsLight}>
       {({ className, style, tokens, getTokenProps }) => (
         <pre>
-          <Code className={classNames(className, "whitespace-pre-wrap")} style={style} title={supportedLanguage}>
+          <Code className={classNames(className, "whitespace-pre-wrap")} style={{ ...style, backgroundColor: 'transparent' }} title={supportedLanguage}>
             {tokens.map((line, lineIndex) => (
               <Fragment key={lineIndex}>
                 {line

package/src/mdx/icon.tsx

@@ -51,21 +51,28 @@ export function Icon({
   }
 
   // --- Try Font Awesome ---
-  const faSet = iconSets[iconType] ?? solidIcons
-  const iconKey = `fa${pascalCase}` as keyof typeof faSet
-  const faIcon = faSet[iconKey]
+  // Fall back to the brands set: Lucide 1.x removed all brand icons
+  // (github, twitter, npm, ...), which live only in FA brands.
+  const iconKey = `fa${pascalCase}`
+  const setsToTry: Array<keyof typeof iconSets> =
+    iconType === 'brands' ? ['brands'] : [iconType, 'brands']
 
-  if (faIcon && typeof faIcon === 'object' && 'iconName' in faIcon) {
-    library.add(faIcon)
-    return (
-      <FontAwesomeIcon
-        icon={[prefixes[iconType] || 'fas', faIcon.iconName] as any}
-        className={classNames("stroke-black dark:stroke-white", className)}
-        color={color as any}
-        size={size as any}
-        {...rest as any}
-      />
-    )
+  for (const setName of setsToTry) {
+    const faSet = iconSets[setName] ?? solidIcons
+    const faIcon = faSet[iconKey as keyof typeof faSet]
+
+    if (faIcon && typeof faIcon === 'object' && 'iconName' in faIcon) {
+      library.add(faIcon)
+      return (
+        <FontAwesomeIcon
+          icon={[prefixes[setName] || 'fas', faIcon.iconName] as any}
+          className={classNames("stroke-black dark:stroke-white", className)}
+          color={color as any}
+          size={size as any}
+          {...rest as any}
+        />
+      )
+    }
   }
 
   console.warn(`⚠️ Icon not found: "${icon}" (converted to ${iconKey}) in ${iconType}`)

package/src/mdx/latex.tsx

@@ -16,6 +16,11 @@ interface LatexProps {
 
 export function Latex({ children }: LatexProps) {
   const expression = extractText(children).trim();
+
+  if (typeof window === 'undefined') {
+    return <div className="my-4"><code>{expression}</code></div>
+  }
+
   const containerRef = useRef<HTMLDivElement>(null)
   const [error, setError] = useState<string | null>(null)
   const [isLoading, setIsLoading] = useState(true)

package/src/mdx/mdx.tsx

@@ -22,20 +22,28 @@ export { UnorderedList as ul, OrderedList as ol, ListItem as li } from './list';
 export { AsyncAPI } from './async-api';
 export { Source } from './source';
 
-// Lazy-loaded heavy components — only downloaded when a page uses them
+// Lazy-loaded heavy components — only downloaded when a page uses them.
+// SSR guard at this level prevents Suspense from rendering in Node.js
+// (renderToString can't resolve lazy components).
 const LazyAPIPlayground = lazy(() => import('./api-playground').then(m => ({ default: m.APIPlayground })));
-export const APIPlayground = (props: any) => (
-  <Suspense fallback={<Loading />}>
-    <LazyAPIPlayground {...props} />
-  </Suspense>
-);
+export const APIPlayground = (props: any) => {
+  if (typeof window === 'undefined') return null;
+  return (
+    <Suspense fallback={<Loading />}>
+      <LazyAPIPlayground {...props} />
+    </Suspense>
+  );
+};
 
 const LazyWebSocketPlayground = lazy(() => import('./websocket-playground').then(m => ({ default: m.WebSocketPlayground })));
-export const WebSocketPlayground = (props: any) => (
-  <Suspense fallback={<Loading />}>
-    <LazyWebSocketPlayground {...props} />
-  </Suspense>
-);
+export const WebSocketPlayground = (props: any) => {
+  if (typeof window === 'undefined') return null;
+  return (
+    <Suspense fallback={<Loading />}>
+      <LazyWebSocketPlayground {...props} />
+    </Suspense>
+  );
+};
 
 export const wrapper = ({ children }: { children: preact.ComponentChildren }) => {
   const ref = useRef<HTMLDivElement>(null);

package/src/mdx/mermaid.tsx

@@ -16,6 +16,15 @@ function fixNodeLabelsWithSpecialChars(content: string): string {
     });
 }
 
+// Deterministic djb2 hash — btoa throws on non-Latin-1 content (e.g. "→", CJK, emoji)
+function hashContent(content: string): string {
+    let hash = 5381;
+    for (let i = 0; i < content.length; i++) {
+        hash = ((hash << 5) + hash + content.charCodeAt(i)) >>> 0;
+    }
+    return hash.toString(16);
+}
+
 export function MermaidRenderer({ content }: { content: string }) {
     const mermaidRef = useRef<HTMLDivElement>(null)
     const [isFullscreen, setIsFullscreen] = useState(false)
@@ -23,7 +32,7 @@ export function MermaidRenderer({ content }: { content: string }) {
     const [error, setError] = useState<string | null>(null)
     const [isValid, setIsValid] = useState<boolean | null>(null)
 
-    const diagramId = useMemo(() => `mermaid-${btoa(content).replace(/[^a-zA-Z0-9]/g, '').substring(0, 10)}`, [content])
+    const diagramId = useMemo(() => `mermaid-${hashContent(content)}`, [content])
 
     useEffect(() => {
         let mounted = true

package/src/mdx/processor.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { preprocessMdxContent } from './processor';
+
+async function run(input: string): Promise<string> {
+  const result = await preprocessMdxContent(input);
+  expect(result.success).toBe(true);
+  return result.processedContent!;
+}
+
+describe('preprocessMdxContent', () => {
+  it('strips YAML frontmatter', async () => {
+    const output = await run('---\ntitle: Hello\n---\n# Heading\n');
+    expect(output).not.toContain('title: Hello');
+    expect(output).toContain('# Heading');
+  });
+
+  it('converts URLs in angle brackets to markdown links', async () => {
+    const output = await run('Visit <https://example.com/docs> now');
+    expect(output).toBe('Visit [https://example.com/docs](https://example.com/docs) now');
+  });
+
+  it('preserves angle-bracket URLs inside fenced code blocks', async () => {
+    const input = '```\ncurl <https://example.com>\n```\n';
+    expect(await run(input)).toBe(input);
+  });
+
+  it('preserves angle-bracket URLs inside inline code', async () => {
+    const input = 'run `curl <https://example.com>` locally';
+    expect(await run(input)).toBe(input);
+  });
+
+  it('tracks code-block state across multiple fences', async () => {
+    const input = [
+      '```',
+      '<https://in-block.com>',
+      '```',
+      '<https://outside.com>',
+      '```',
+      '<https://in-block-2.com>',
+      '```',
+    ].join('\n');
+    const output = await run(input);
+    expect(output).toContain('<https://in-block.com>');
+    expect(output).toContain('<https://in-block-2.com>');
+    expect(output).toContain('[https://outside.com](https://outside.com)');
+  });
+});

package/src/mdx/step.tsx

@@ -16,11 +16,11 @@ export function Steps({ children }: { children: preact.ComponentChildren }) {
               },
               'relative'
             )}>
-              <div aria-hidden="true" className="absolute top-10 left-4 h-full w-[0.5px] bg-gray-300/50 dark:bg-gray-600/50" style={{ top: '40px', height: 'calc(100% - 44px)' }} />
+              <div aria-hidden="true" className="absolute top-10 left-4 h-full w-[0.5px]" style={{ top: '40px', height: 'calc(100% - 44px)', backgroundColor: 'color-mix(in oklch, var(--brand-foreground) 30%, transparent)' }} />
               <div className="group relative flex items-start">
                 <span className="flex h-9 items-center">
-                  <span className="relative z-10 flex size-8 items-center justify-center rounded-full bg-white dark:bg-gray-800 group-hover:border-gray-400">
-                    <span className="text-sm font-medium text-gray-500 dark:text-white">
+                  <span className="relative z-10 flex size-8 items-center justify-center rounded-full border" style={{ borderColor: 'var(--brand-foreground)', backgroundColor: 'color-mix(in oklch, var(--brand-foreground) 12%, transparent)' }}>
+                    <span className="text-sm font-medium" style={{ color: 'var(--brand-foreground)' }}>
                       {stepIdx + 1}
                     </span>
                   </span>

package/src/mdx/websocket-playground.tsx

@@ -750,6 +750,8 @@ function WebSocketPlaygroundInternal({
 
 // Main exported component with Sheet wrapper
 export function WebSocketPlayground(props: WebSocketPlaygroundProps) {
+  if (typeof window === 'undefined') return null
+
   const [showPlayground, setShowPlayground] = useState(false)
 
   const handleShowPlayground = () => {

package/src/plugins/analytics-injector.ts

@@ -17,19 +17,21 @@ export function analyticsInjector(): Plugin {
         const config = JSON.parse(readFileSync(doryJsonPath, 'utf-8'));
 
         if (config.analytics?.posthog?.token) {
-          const token = config.analytics.posthog.token;
-          const apiHost = config.analytics.posthog.apiHost || 'https://us.i.posthog.com';
+          // JSON.stringify so config-controlled values are safely escaped
+          // when inlined into the script (quotes, </script>, etc.)
+          const token = JSON.stringify(String(config.analytics.posthog.token)).replace(/</g, '\\u003c');
+          const apiHost = JSON.stringify(String(config.analytics.posthog.apiHost || 'https://us.i.posthog.com')).replace(/</g, '\\u003c');
 
           const script = `
     <script>
         !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture identify setPersonProperties group resetGroups reset get_distinct_id getGroups get_session_id opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
-        posthog.init('${token}', {
-            api_host: '${apiHost}',
+        posthog.init(${token}, {
+            api_host: ${apiHost},
             person_profiles: 'identified_only',
         })
     </script>`;
 
-          return html.replace('</head>', `${script}\n  </head>`);
+          return html.replace('</head>', () => `${script}\n  </head>`);
         }
 
         return html;