@clidey/dory 0.45.0 → 0.47.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clidey/dory",
   "private": false,
-  "version": "0.45.0",
+  "version": "0.47.0",
   "type": "module",
   "description": "A CLI tool for building and previewing documentation sites",
   "keywords": [
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "npm run build:cli && tsc -b && npm run build:docs",
+    "build": "npm run build:cli && tsc -b",
     "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",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@algolia/autocomplete-core": "1.19.5",
-    "@clidey/ux": "0.39.0",
+    "@clidey/ux": "0.40.0",
     "@fortawesome/fontawesome-svg-core": "7.2.0",
     "@fortawesome/free-brands-svg-icons": "7.2.0",
     "@fortawesome/free-regular-svg-icons": "7.2.0",

package/scripts/render-routes.mjs

@@ -2,6 +2,7 @@
  * Post-build SSR rendering script.
  * Reads the SSR bundle from dist-ssr/, renders each route to HTML,
  * and injects the content into the prerendered HTML files in dist/.
+ * Also inlines frontmatter JSON so the client can hydrate without fetching.
  */
 import { readFileSync, writeFileSync, existsSync, rmSync } from 'fs';
 import { resolve, dirname } from 'path';
@@ -31,14 +32,22 @@ const frontmatter = JSON.parse(readFileSync(frontmatterPath, 'utf-8'));
 let count = 0;
 let failed = 0;
 
-function injectSSR(htmlPath, ssrHtml) {
+function injectSSR(htmlPath, ssrHtml, routePath) {
   let html = readFileSync(htmlPath, 'utf-8');
 
+  // Inject SSR-rendered content into #app
   html = html.replace(
     '<div id="app"></div>',
     `<div id="app">${ssrHtml}</div>`
   );
 
+  // Blocking theme script — sets dark class before first paint to prevent flash.
+  // Inline frontmatter JSON so the client can read it synchronously.
+  html = html.replace(
+    '</head>',
+    `<script>(function(){try{var t=localStorage.getItem("@clidey/dory/theme");if(t==="dark"||(t==="system"||!t)&&window.matchMedia("(prefers-color-scheme:dark)").matches)document.documentElement.classList.add("dark")}catch(e){}})();window.__DORY_FRONTMATTER__=${JSON.stringify(frontmatter)};window.__DORY_ROUTE__=${JSON.stringify(routePath)};</script>\n</head>`
+  );
+
   html = html.replace(
     '<noscript>You need to enable JavaScript to run this app.</noscript>',
     '<noscript>JavaScript enhances this page with interactive features.</noscript>'
@@ -47,7 +56,7 @@ function injectSSR(htmlPath, ssrHtml) {
   writeFileSync(htmlPath, html, 'utf-8');
 }
 
-// Render each route
+// Render each route — pass frontmatter so SSR can build navigation titles
 for (const page of frontmatter) {
   const routePath = page.path;
   if (!routePath || routePath === '/') continue;
@@ -56,10 +65,10 @@ for (const page of frontmatter) {
   if (!existsSync(htmlPath)) continue;
 
   try {
-    const ssrHtml = await render(routePath);
+    const ssrHtml = await render(routePath, frontmatter);
     if (!ssrHtml) continue;
 
-    injectSSR(htmlPath, ssrHtml);
+    injectSSR(htmlPath, ssrHtml, routePath);
     count++;
   } catch (error) {
     console.warn(`⚠️  SSR failed for ${routePath}: ${error.message}`);
@@ -73,9 +82,9 @@ try {
   if (existsSync(rootHtmlPath) && frontmatter.length > 0) {
     const firstRoute = frontmatter[0].path;
     if (firstRoute) {
-      const ssrHtml = await render(firstRoute);
+      const ssrHtml = await render(firstRoute, frontmatter);
       if (ssrHtml) {
-        injectSSR(rootHtmlPath, ssrHtml);
+        injectSSR(rootHtmlPath, ssrHtml, firstRoute);
         count++;
       }
     }

package/src/components/routes.tsx

@@ -1,115 +1,63 @@
-import { useEffect, useState } from 'preact/hooks';
+import { useEffect, useMemo } from 'preact/hooks';
 import { Route, Router, useLocation } from 'wouter-preact';
 import { usePathname } from './hooks';
 import { ALL_NAVIGATION, ALL_PAGES, pathFromFilename } from './store';
-import { Loading } from './loading';
 
 
 export default function Routes() {
-  const [routes, setRoutes] = useState<any[]>([]);
   const pathname = usePathname();
   const [, navigate] = useLocation();
-  const [loading, setLoading] = useState(true);
 
+  // Redirect root to the first page so the URL reflects the actual content
   useEffect(() => {
-    const links = document.querySelectorAll('.dory-navigation a');
-    const listeners: (() => void)[] = [];
-    const preloaded = new Set();
-  
-    links.forEach(link => {
-      const href = link.getAttribute('href');
-      if (!href) return;
-  
-      const loaderEntry = Object.entries(ALL_PAGES).find(
-        ([path]) => path === href
-      );
-  
-      if (!loaderEntry) return;
-  
-      const [path, loader] = loaderEntry;
-  
-      const handleMouseEnter = () => {
-        if (!preloaded.has(path)) {
-          loader();
-          preloaded.add(path);
-        }
-      };
-  
-      link.addEventListener('mouseenter', handleMouseEnter);
-      listeners.push(() => link.removeEventListener('mouseenter', handleMouseEnter));
-    });
-  
-    return () => {
-      listeners.forEach(unsub => unsub());
-    };
-  }, []);
+    if (pathname === '/') {
+      const firstPage = ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href;
+      if (firstPage) navigate(firstPage, { replace: true });
+    }
+  }, [pathname]);
 
-  useEffect(() => {
-    setLoading(true);
-    const loadRoutes = async () => {
-      try {
-        // For root path, load the first navigation page
-        const targetPath = pathname === '/' ? ALL_NAVIGATION[0].groups[0].pages[0].href : pathname;
+  const route = useMemo(() => {
+    let targetPath = pathname;
+    if (pathname === '/') {
+      const ssrRoute = typeof window !== 'undefined' && (window as any).__DORY_ROUTE__;
+      targetPath = ssrRoute || ALL_NAVIGATION[0].groups[0].pages[0].href;
+    }
 
-        const entries = await Promise.all(
-          Object.entries(ALL_PAGES).filter(([path]) => path === targetPath).map(async ([path, loader]) => {
-            const module = await loader();
-            const routePath = pathname === '/' ? '/' : pathFromFilename(path);
-            return {
-              path: routePath,
-              component: module.default,
-            };
-          })
-        );
-        setRoutes(entries);
-      } catch (error) {
-        console.error('Failed to load route:', error);
-        setRoutes([]);
-      } finally {
-        setLoading(false);
-      }
-    };
+    const entry = Object.entries(ALL_PAGES).find(([path]) => path === targetPath);
+    if (!entry) return null;
 
-    loadRoutes();
+    const [path, mod] = entry;
+    return {
+      path: pathname === '/' ? '/' : pathFromFilename(path),
+      component: (mod as any).default,
+    };
   }, [pathname]);
 
-  useEffect(() => {
+  // 404
+  if (!route) {
     const page = ALL_NAVIGATION.find((tab) => tab.groups.find((group) => group.pages.find((page) => page.href === pathname)));
     if (!page && pathname !== '/') {
-      setRoutes([{
-        path: pathname,
-        component: () => (
-          <div className="flex flex-col items-center justify-center min-h-[50vh] p-8">
-            <h1 className="text-6xl font-bold text-gray-300 dark:text-gray-700 mb-4">404</h1>
-            <h2 className="text-2xl font-semibold mb-4">Page Not Found</h2>
-            <p className="text-gray-600 dark:text-gray-400 mb-6 text-center max-w-md">
-              The page <code className="px-1.5 py-0.5 bg-gray-100 dark:bg-gray-800 rounded text-sm">{pathname}</code> doesn't exist.
-            </p>
-            <button
-              onClick={() => navigate(ALL_NAVIGATION[0].groups[0].pages[0].href)}
-              className="px-4 py-2 text-sm font-medium rounded-md bg-[var(--brand-primary)] text-white hover:opacity-90 transition-opacity"
-            >
-              Go to Home
-            </button>
-          </div>
-        )
-      }]);
-      setLoading(false);
+      return (
+        <div className="flex flex-col items-center justify-center min-h-[50vh] p-8">
+          <h1 className="text-6xl font-bold text-gray-300 dark:text-gray-700 mb-4">404</h1>
+          <h2 className="text-2xl font-semibold mb-4">Page Not Found</h2>
+          <p className="text-gray-600 dark:text-gray-400 mb-6 text-center max-w-md">
+            The page <code className="px-1.5 py-0.5 bg-gray-100 dark:bg-gray-800 rounded text-sm">{pathname}</code> doesn't exist.
+          </p>
+          <button
+            onClick={() => navigate(ALL_NAVIGATION[0].groups[0].pages[0].href)}
+            className="px-4 py-2 text-sm font-medium rounded-md bg-[var(--brand-primary)] text-white hover:opacity-90 transition-opacity"
+          >
+            Go to Home
+          </button>
+        </div>
+      );
     }
-  }, [pathname]);
-
-  useEffect(() => {
-    window.scrollTo({ top: 0, behavior: 'smooth' });
-  }, [pathname]);
-  
-
-  if (loading) return <div className="h-[25vh] flex grow"><Loading /></div>;
+  }
 
   return (
     <Router>
-      {routes.map(({ path, component: Component }) => (
-        <Route key={path} path={path} component={Component} />
-      ))}
+      {route && <Route key={route.path} path={route.path} component={route.component} />}
     </Router>
   );
 }

package/src/components/search.tsx

@@ -374,6 +374,7 @@ function useSearchProps() {
   return {
     inputProps: {
       ref: inputRef,
+      readOnly: true,
       onClick() {
         setOpen(true)
       },

package/src/components/store.ts

@@ -6,9 +6,12 @@ import { addToSearchIndex } from './search-index';
 
 const config = docsConfig as DoryConfig;
 
+// Eager-load all page modules so they're available synchronously.
+// This eliminates the async loading spinner in Routes and enables
+// proper hydrate() — the first render matches the SSR DOM.
 export const ALL_PAGES = Object.fromEntries(
-  Object.entries(import.meta.glob<{ default: ComponentType; }>('../../docs/**/*.mdx'))
-    .map(([path, loader]) => [pathFromFilename(path), loader])
+  Object.entries(import.meta.glob<{ default: ComponentType; }>('../../docs/**/*.mdx', { eager: true }))
+    .map(([path, mod]) => [pathFromFilename(path), mod])
 );
 export const ALL_OPENAPI = Object.fromEntries(
   Object.entries(import.meta.glob<{ default: string }>('../../docs/**/openapi.json', { query: 'raw', eager: true }))
@@ -59,30 +62,26 @@ export function pathFromFilename(filename: string): string {
         .toLowerCase();
 }
 
-function parseFrontMatter(content: string) {
-    const frontMatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!frontMatterMatch) return { data: {}, content };
-    
-    const frontMatter = frontMatterMatch[1];
-    const data: Record<string, any> = {};
-    
-    frontMatter.split('\n').forEach(line => {
-        const [key, ...valueParts] = line.split(':');
-        if (key && valueParts.length) {
-        const value = valueParts.join(':').trim();
-        data[key.trim()] = value.replace(/^["']|["']$/g, ''); // Remove quotes if present
-        }
-    });
-
-    return { data, content: content.slice(frontMatterMatch[0].length) };
-}
 
 export let completeFrontMatter: Record<string, any>[] = [];
+export function isFrontmatterReady() { return preloadedFrontMatter !== null; }
 let preloadedFrontMatter: Record<string, any>[] | null = null;
 
-// Preload frontmatter from JSON file (optimized approach)
+// Check for inlined frontmatter from SSR (available synchronously, no fetch needed)
+if (typeof window !== 'undefined' && (window as any).__DORY_FRONTMATTER__) {
+    preloadedFrontMatter = (window as any).__DORY_FRONTMATTER__;
+    completeFrontMatter = [...preloadedFrontMatter!];
+    for (const fm of preloadedFrontMatter!) {
+        updateNavigationTitle(fm.path, fm.title);
+    }
+    delete (window as any).__DORY_FRONTMATTER__;
+    // Build search index in the background after the page has fully rendered
+    setTimeout(() => addPreloadedContentToSearch(), 2000);
+}
+
+// Preload frontmatter from JSON file (fallback when no inline data)
 export async function preloadFrontmatter() {
-    if (preloadedFrontMatter) return; // Already loaded
+    if (preloadedFrontMatter) return; // Already loaded (inline or previous fetch)
 
     try {
         const response = await fetch('/frontmatter.json');
@@ -106,33 +105,23 @@ export async function preloadFrontmatter() {
     }
 }
 
-// Add preloaded content to search index (runs in background, never blocks rendering)
+// Add preloaded content to search index (runs in background, never blocks rendering).
+// Fetches pre-built search-content.json generated at build time — no ?raw glob needed.
 async function addPreloadedContentToSearch() {
-    if (!preloadedFrontMatter) return;
-
-    const mdxFiles = import.meta.glob<{ default: string }>('../../docs/**/*.mdx', { query: '?raw' });
-    const fileEntries = Object.entries(mdxFiles);
-
-    // Index in batches to avoid firing hundreds of requests at once
-    const BATCH_SIZE = 10;
-    for (let i = 0; i < preloadedFrontMatter.length; i += BATCH_SIZE) {
-        const batch = preloadedFrontMatter.slice(i, i + BATCH_SIZE);
-        await Promise.all(
-            batch.map(async (fm) => {
-                const fileEntry = fileEntries.find(([filePath]) => pathFromFilename(filePath) === fm.path);
-                if (fileEntry) {
-                    try {
-                        const [, loader] = fileEntry;
-                        const rawContent = (await loader()).default;
-                        const { content } = parseFrontMatter(rawContent);
-
-                        await addToSearchIndex(fm.path, { title: fm.title }, content);
-                    } catch (error) {
-                        console.warn(`Failed to index ${fm.path}:`, error);
-                    }
-                }
-            })
-        );
+    try {
+        const response = await fetch('/search-content.json');
+        if (!response.ok) return;
+        const searchContent: Array<{ path: string; title: string; content: string }> = await response.json();
+
+        for (const entry of searchContent) {
+            try {
+                await addToSearchIndex(entry.path, { title: entry.title }, entry.content);
+            } catch (error) {
+                console.warn(`Failed to index ${entry.path}:`, error);
+            }
+        }
+    } catch (error) {
+        console.warn('Failed to load search content:', error);
     }
 }
 
@@ -146,53 +135,40 @@ export async function loadMDXFrontMatterForPath(pathname: string) {
     // Check if already loaded in completeFrontMatter
     if (completeFrontMatter.find(fm => fm.path === pathname)) return;
 
-    // Fallback to dynamic loading
-    const mdxFiles = import.meta.glob<{ default: string }>('../../docs/**/*.mdx', { query: '?raw' });
-    const fileEntries = Object.entries(mdxFiles);
-
-    const fileEntry = fileEntries.find(([path]) => pathFromFilename(path) === pathname);
-    if (!fileEntry) return;
-
-    const [path, loader] = fileEntry;
-    const rawContent = (await loader()).default;
-    const { data, content } = parseFrontMatter(rawContent);
-    const filename = pathFromFilename(path);
-
-    updateNavigationTitle(filename, data.title);
-    await addToSearchIndex(filename, data, content);
-
-    const frontmatterItem = { ...data, path: filename };
-    completeFrontMatter = [...completeFrontMatter, frontmatterItem];
+    // Fallback: fetch frontmatter.json for this page's metadata
+    try {
+        const response = await fetch('/frontmatter.json');
+        if (response.ok) {
+            const allFm: Record<string, any>[] = await response.json();
+            const fm = allFm.find(f => f.path === pathname);
+            if (fm) {
+                updateNavigationTitle(pathname, fm.title);
+                completeFrontMatter = [...completeFrontMatter, fm];
+            }
+        }
+    } catch {
+        // Non-fatal — page will still render, just without title in nav
+    }
 }
 
 // Load all remaining frontmatter (after initial load) - optimized with fallback
 export async function loadAllMDXFrontMatter(pathname: string) {
-    // If we have preloaded data, we're already done
-    if (preloadedFrontMatter) {
-        return;
-    }
-
-    // Fallback to dynamic loading
-    const mdxFiles = import.meta.glob<{ default: string }>('../../docs/**/*.mdx', { query: '?raw' });
-    const fileEntries = Object.entries(mdxFiles);
+    if (preloadedFrontMatter) return;
 
-    const remainingEntries = fileEntries.filter(([path]) => pathFromFilename(path) !== pathname);
-    const newFrontmatter: Record<string, any>[] = [];
-
-    await Promise.all(
-        remainingEntries.map(async ([path, loader]) => {
-            const rawContent = (await loader()).default;
-            const { data, content } = parseFrontMatter(rawContent);
-            const filename = pathFromFilename(path);
-
-            updateNavigationTitle(filename, data.title);
-            await addToSearchIndex(filename, data, content);
-
-            newFrontmatter.push({ ...data, path: filename });
-        })
-    );
+    try {
+        const response = await fetch('/frontmatter.json');
+        if (!response.ok) return;
+        const allFm: Record<string, any>[] = await response.json();
 
-    completeFrontMatter = [...completeFrontMatter, ...newFrontmatter];
+        for (const fm of allFm) {
+            if (fm.path !== pathname) {
+                updateNavigationTitle(fm.path, fm.title);
+                completeFrontMatter = [...completeFrontMatter, fm];
+            }
+        }
+    } catch {
+        // Non-fatal
+    }
 }
 
 // Shared helper

package/src/entry-server.tsx

@@ -1,7 +1,11 @@
-import {renderToString} from 'preact-render-to-string';
-import {Router} from 'wouter-preact';
-import {MDXProvider} from '@mdx-js/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';
+
+const config = docsConfig as any;
 
 function pathFromFilename(filename: string): string {
   return filename
@@ -16,67 +20,24 @@ 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>
-  );
-}
-
-// 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>
-  );
-}
-
-// 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} />;
-}
-
-// 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>[]) {
+  return config.navigation.tabs.map((tab: any) => ({
+    title: tab.tab,
+    groups: tab.groups.map((group: any) => ({
+      title: group.group,
+      pages: group.pages.map((page: string) => {
+        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 '';
 
@@ -84,20 +45,149 @@ export async function render(routePath: string): Promise<string> {
     const module = await loader() as any;
     const Content = module.default;
 
+    const navigation = buildNavigation(frontmatter);
+    const pageFm = frontmatter?.find((fm: any) => fm.path === routePath);
+
+    // Find group/page titles (Layout uses swapped names: "title: group, group: title")
+    let groupTitle = '';
+    const currentTab = navigation.find((tab: any) =>
+      tab.groups.some((group: any) =>
+        group.pages.some((page: any) => page.href === routePath)
+      )
+    );
+    if (currentTab) {
+      for (const group of currentTab.groups) {
+        if (group.pages.some((p: any) => p.href === routePath)) {
+          groupTitle = group.title;
+        }
+      }
+    }
+
+    // Prev/next
+    const allLinks = navigation.flatMap((tab: any) =>
+      tab.groups.flatMap((group: any) => group.pages)
+    );
+    const linkIndex = allLinks.findIndex((link: any) => 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">
+                  {/* 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">
+                        <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: any) => {
+                            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: any) => (
+                                  <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: any) => (
+                                        <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,4 +1,4 @@
-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'
@@ -7,6 +7,10 @@ import { loadFonts } from './utils/fonts'
 import { loadColors } from './utils/colors'
 import { Toaster } from '@clidey/ux'
 import { ThemeProvider } from '@clidey/ux'
+import { preloadFrontmatter } from './components/store'
+
+// Start frontmatter loading immediately — if inlined from SSR, this is a no-op.
+preloadFrontmatter()
 
 // Load fonts and colors before rendering the app
 loadFonts()
@@ -14,12 +18,22 @@ loadColors()
 
 const AppWithMDX = withMDX(App)
 
-render(
+const appRoot = document.getElementById('app')!
+const hasSSRContent = appRoot.children.length > 0
+
+const tree = (
     <ThemeProvider 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/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/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/frontmatter-dev-server.ts

@@ -137,10 +137,47 @@ function generateFrontmatterJson(docsDir: string): Array<Record<string, any>> {
   return frontmatterArray;
 }
 
+// Strip MDX/JSX syntax to extract plain text for search indexing
+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();
+}
+
 export function frontmatterDevServer(): Plugin {
   return {
     name: 'frontmatter-dev-server',
     configureServer(server) {
+      // Serve search content for client-side indexing
+      server.middlewares.use('/search-content.json', (req, res, next) => {
+        if (req.method !== 'GET') return next();
+        try {
+          const docsDir = path.join(process.cwd(), 'docs');
+          const fmArray = generateFrontmatterJson(docsDir);
+          const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
+          const searchContent = fmArray.map(fm => {
+            const entry = Object.entries(mdxFilesMap).find(([, fp]) => pathFromFilename(fp, docsDir) === fm.path);
+            if (!entry) return { path: fm.path, title: fm.title || '', content: '' };
+            const raw = fs.readFileSync(entry[1], 'utf-8');
+            const { content } = parseFrontmatter(raw);
+            return { path: fm.path, title: fm.title || '', content: stripMdxToText(content) };
+          });
+          const json = JSON.stringify(searchContent);
+          res.setHeader('Content-Type', 'application/json; charset=utf-8');
+          res.end(json);
+        } catch (error) {
+          console.error('Error generating search content:', error);
+          res.statusCode = 500;
+          res.end('Internal Server Error');
+        }
+      });
+
       server.middlewares.use('/frontmatter.json', (req, res, next) => {
         if (req.method !== 'GET') {
           return next();

package/src/plugins/frontmatter-generator.ts

@@ -142,6 +142,41 @@ function generateFrontmatterJson(docsDir: string): Array<Record<string, any>> {
   return frontmatterArray;
 }
 
+// Strip MDX/JSX syntax to extract plain text for search indexing
+function stripMdxToText(content: string): string {
+  return content
+    .replace(/^import\s+.*$/gm, '')           // import statements
+    .replace(/^export\s+.*$/gm, '')           // export statements
+    .replace(/```[\s\S]*?```/g, '')           // fenced code blocks
+    .replace(/<[^>]+>/g, '')                  // JSX/HTML tags
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')  // markdown links → text
+    .replace(/[#*_~`>|]/g, '')               // markdown syntax chars
+    .replace(/\n{3,}/g, '\n\n')              // collapse blank lines
+    .trim();
+}
+
+// Generate search content JSON: [{ path, title, content }]
+function generateSearchContentJson(docsDir: string, frontmatterArray: Array<Record<string, any>>): Array<Record<string, any>> {
+  const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
+  const searchContent: Array<Record<string, any>> = [];
+
+  for (const fm of frontmatterArray) {
+    // Find the MDX file for this frontmatter entry
+    const fileEntry = Object.entries(mdxFilesMap).find(([, filePath]) =>
+      pathFromFilename(filePath, docsDir) === fm.path
+    );
+    if (!fileEntry) continue;
+
+    const rawContent = fs.readFileSync(fileEntry[1], 'utf-8');
+    const { content } = parseFrontmatter(rawContent);
+    const text = stripMdxToText(content);
+
+    searchContent.push({ path: fm.path, title: fm.title || '', content: text });
+  }
+
+  return searchContent;
+}
+
 export function frontmatterGenerator(options: FrontmatterGeneratorOptions = {}): Plugin {
   return {
     name: 'frontmatter-generator',
@@ -156,9 +191,19 @@ export function frontmatterGenerator(options: FrontmatterGeneratorOptions = {}):
         source: jsonContent
       });
 
+      // Also generate search content for client-side indexing
+      const searchContent = generateSearchContentJson(docsDir, frontmatterArray);
+      const searchJson = JSON.stringify(searchContent);
+
+      this.emitFile({
+        type: 'asset',
+        fileName: 'search-content.json',
+        source: searchJson
+      });
+
       console.log(`✅ Generated frontmatter JSON file`);
       console.log(`📄 Processed ${frontmatterArray.length} MDX files`);
-      console.log(`📝 Total JSON size: ${jsonContent.length} characters`);
+      console.log(`🔍 Generated search content (${searchContent.length} pages, ${(searchJson.length / 1024).toFixed(0)} KB)`);
     }
   };
 }

package/src/plugins/sanitize.ts

@@ -24,7 +24,7 @@ const KNOWN_COMPONENTS = [
   'Callout', 'Note', 'Warning', 'Info', 'Tip', 'Check',
   'Latex', 'API', 'Expandable', 'ResponseField', 'Properties', 'Property',
   'Steps', 'Step', 'table', 'th', 'td', 'ul', 'ol', 'li',
-  'APIPlayground', 'WebSocketPlayground', 'AsyncAPI', 'Source',
+  'APIPlayground', 'WebSocketPlayground', 'AsyncAPI', 'Source', 'Tag',
   // Common HTML elements that should be preserved
   'div', 'span', 'br', 'hr', 'strong', 'em', 'b', 'i', 'u', 's',
   'blockquote', 'nav', 'section', 'article', 'header', 'footer', 'main',

package/src/ui/layout.tsx

@@ -1,7 +1,7 @@
 import type { ComponentChildren } from 'preact';
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks';
 import { Navigation } from '../components/navigation';
-import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, ALL_PAGES, pathFromFilename, preloadFrontmatter, ALL_ASYNCAPI } from '../components/store';
+import { ALL_NAVIGATION, ALL_OPENAPI, completeFrontMatter, loadMDXFrontMatterForPath, loadAllMDXFrontMatter, ALL_PAGES, pathFromFilename, preloadFrontmatter, ALL_ASYNCAPI, isFrontmatterReady } from '../components/store';
 import { usePathname } from '../components/hooks';
 import { OpenAPI } from '../mdx/open-api';
 import { AsyncAPI } from '../mdx/async-api';
@@ -25,8 +25,9 @@ const prompt = (pathname: string) => `Please read and analyze the content from t
   `Please provide clear, detailed explanations and examples where relevant.`;
 
 export default function Layout({ children }: LayoutProps) {
-  const [loading, setLoading] = useState(true);
-  const pathname = usePathname();
+  const [loading, setLoading] = useState(!isFrontmatterReady());
+  const rawPathname = usePathname();
+  const pathname = rawPathname === '/' ? ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href ?? '/' : rawPathname;
   const { showNotification } = useNotification();
   const isEmbedded = useIsEmbedded();
 
@@ -35,9 +36,8 @@ export default function Layout({ children }: LayoutProps) {
   }, [pathname]);
 
   const handleCopyMDX = useCallback(() => {
-    ALL_PAGES[pathFromFilename(pathname)]().then((mdx) => {
-      navigator.clipboard.writeText(mdx.default.toString());
-    });
+    const mod = ALL_PAGES[pathFromFilename(pathname)];
+    if (mod) navigator.clipboard.writeText((mod as any).default.toString());
     showNotification('Copied to clipboard');
   }, []);
   const handleOpenChatGPT = useCallback(() => {
@@ -69,9 +69,9 @@ export default function Layout({ children }: LayoutProps) {
   ], [handleOpenMDX, handleCopyMDX, handleOpenChatGPT, handleOpenAnthropic]);
 
   useEffect(() => {
-    // Try to preload frontmatter first (optimized approach)
+    // Try to preload frontmatter first (optimized approach).
+    // If inline data was available from SSR, preloadFrontmatter() resolves immediately.
     preloadFrontmatter().then(() => {
-      // If preloading succeeds, we're done
       setLoading(false);
     }).catch(() => {
       // Fallback to the original approach
@@ -87,6 +87,7 @@ export default function Layout({ children }: LayoutProps) {
     });
   }, [pathname]);
 
+
   const { title: group, group: title, page } = useMemo(() => {
     const group = ALL_NAVIGATION.flatMap((tab) =>
       tab.groups.find((group) =>

package/vite.config.ssr.ts

@@ -14,9 +14,10 @@ export default defineConfig({
     mdx(getMdxConfig(false)),
   ],
   resolve: {
+    dedupe: ['preact', 'preact/compat', 'preact/hooks', 'preact/jsx-runtime', 'preact/compat/jsx-runtime'],
     alias: {
       react: 'preact/compat',
-      'react-dom': 'preact/compat'
+      'react-dom': 'preact/compat',
     }
   },
   build: {

package/vite.config.ts

@@ -36,9 +36,10 @@ export default defineConfig(({ command }) => ({
     prerender(),
   ],
   resolve: {
+    dedupe: ['preact', 'preact/compat', 'preact/hooks', 'preact/jsx-runtime', 'preact/compat/jsx-runtime'],
     alias: {
       react: 'preact/compat',
-      'react-dom': 'preact/compat'
+      'react-dom': 'preact/compat',
     }
   },
   publicDir: false, // Don't use a public directory since we need to import from docs