@clidey/dory 1.0.8 → 1.10.0

package/src/components/chat-assistant.tsx

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

package/src/components/dropdown.tsx

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

package/src/components/error-boundary.tsx

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

package/src/components/hooks.tsx

@@ -2,6 +2,9 @@ import { useEffect, useState } from 'preact/hooks';
 import { useLocation } from 'wouter-preact';
 import { withBase } from '../utils/base-path';
 
+const initialEmbedParams = typeof window !== 'undefined' && new URLSearchParams(window.location.search).get('embedded') === 'true'
+  ? new URLSearchParams(window.location.search) : null;
+
 /**
  * Strips trailing slash from a pathname (except root "/").
  */
@@ -53,5 +56,21 @@ export const useSearchParams = () => {
  */
 export const useIsEmbedded = () => {
   const searchParams = useSearchParams();
-  return searchParams.get('embedded') === 'true';
+  const [pathname] = useLocation();
+
+  useEffect(() => {
+    if (!initialEmbedParams) return;
+    const params = new URLSearchParams(window.location.search);
+    let changed = false;
+    for (const key of ['embedded', 'parentOrigin', 'theme']) {
+      const value = initialEmbedParams.get(key);
+      if (value !== null && params.get(key) !== value) {
+        params.set(key, value);
+        changed = true;
+      }
+    }
+    if (changed) window.history.replaceState(window.history.state, '', `${window.location.pathname}?${params}${window.location.hash}`);
+  }, [pathname]);
+
+  return searchParams.get('embedded') === 'true' || initialEmbedParams !== null;
 };

package/src/components/navigation.tsx

@@ -1,58 +1,89 @@
-import classNames from 'classnames';
-import { useMemo } from 'preact/hooks';
+import { CatalogIcon } from '@clidey/ux'
+import type { ComponentChildren } from 'preact';
+
 import { Link } from 'wouter-preact';
+import docsConfig from '../../docs/dory.json' with { type: 'json' };
+import type { DoryConfig } from '../types/config';
+import { DocsNavigationView, type NavigationPage } from '../ui/docs-navigation-view';
 import { usePathname } from './hooks';
-import { ALL_NAVIGATION } from './store';
+import { ALL_PAGES, completeFrontMatter, getNavigationForPath } from './store';
+import { contentScope, scopedPath } from '../utils/content-scope';
+import { withBase } from '../utils/base-path';
+
+const config = docsConfig as DoryConfig;
 
-export function Navigation() {
-    const pathname = usePathname();
+type Frontmatter = Record<string, any>;
 
-    const effectivePath = pathname === '/' 
-        ? ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href ?? '/' 
-        : pathname;
+/** Sidebar label for a page. API pages show a method tag and their path or message name. */
+function pageLabel(href: string, title: string, frontmatter: Frontmatter[]): { method?: string; title: string } {
+  const fm = frontmatter.find((entry) => entry.path === href);
+  if (typeof fm?.openapi === 'string') {
+    const [verb, path] = fm.openapi.split(' ');
+    const method = verb.toUpperCase() === 'DELETE' ? 'DEL' : verb.toUpperCase();
+    return { method, title: path ?? title };
+  }
+  if (typeof fm?.asyncapi === 'string') {
+    const [operation] = fm.asyncapi.split(' ');
+    return { method: operation.toLowerCase() === 'publish' ? 'PUB' : 'SUB', title };
+  }
+  return { title };
+}
 
-    const currentTab = useMemo(() => {
-        return ALL_NAVIGATION.find(tab => 
-            tab.groups.some(group => 
-                group.pages.some(page => page.href === effectivePath)
-            )
-        );
-    }, [effectivePath]);
+/** Static-site adapter for Dory's shared documentation navigation. */
+export function Navigation({ frontmatter = completeFrontMatter }: { frontmatter?: Frontmatter[] }) {
+  const pathname = usePathname();
+  const scope = contentScope(config, pathname);
+  const navigation = getNavigationForPath(pathname);
+  const switchTo = (locale: string, version: string) => {
+    const candidate = scopedPath(config, pathname, locale, version);
+    if (ALL_PAGES[candidate]) return candidate;
+    return getNavigationForPath(candidate)[0]?.groups[0]?.pages[0]?.href ?? '/';
+  };
+  const effectivePath = pathname === '/'
+    ? navigation[0]?.groups[0]?.pages[0]?.href ?? '/'
+    : pathname;
+  const groups = navigation.flatMap(tab => tab.groups).map(group => ({
+    title: group.title,
+    pages: group.pages.map(page => {
+      const translatedTitle = frontmatter.find(entry => entry.path === page.href)?.title ?? page.title;
+      return { ...page, ...pageLabel(page.href, translatedTitle, frontmatter) };
+    }),
+  }));
+  const currentVersion = config.versions?.find(version => version.id === scope.version);
+  const versionLabel = currentVersion?.label ?? config.version;
+  const versionSelect = config.versions && config.versions.length > 0 ? <>
+    <CatalogIcon name="up-down" aria-hidden="true" className="h-3.5 w-3.5 text-white/50" />
+    {/* Transparent native select over the card: keyboard and screen-reader friendly. */}
+    <select
+      aria-label="Version"
+      value={scope.version}
+      onChange={event => {
+        const id = (event.target as HTMLSelectElement).value;
+        const version = config.versions?.find(entry => entry.id === id || entry.url === id);
+        const target = version?.url ?? withBase(switchTo(scope.locale, id));
+        window.location.href = target;
+      }}
+      className="absolute inset-0 cursor-pointer opacity-0"
+    >
+      <option value="">{config.version}</option>
+      {config.versions.map(version => <option key={version.id ?? version.url} value={version.id ?? version.url}>{version.label}</option>)}
+    </select>
+  </> : undefined;
+  const languageSelect = config.i18n && config.i18n.locales.length > 1 ?
+    <label className="flex items-center justify-between gap-3 rounded-lg border border-white/10 bg-white/5 px-3 py-2 text-white">
+      <span className="dory-mono-label">Language</span>
+      <select
+        aria-label="Language"
+        value={scope.locale}
+        onChange={event => { window.location.href = withBase(switchTo((event.target as HTMLSelectElement).value, scope.version)); }}
+        className="min-w-0 max-w-32 bg-transparent text-right text-sm text-white"
+      >
+        {config.i18n.locales.map(locale => <option key={locale.code} value={locale.code} className="text-black">{locale.label}</option>)}
+      </select>
+    </label> : undefined;
+  const renderPageLink = (page: NavigationPage, className: string, active: boolean, children: ComponentChildren) =>
+    <Link href={page.href} aria-current={active ? 'page' : undefined} className={className}>{children}</Link>;
 
-    return (
-        <nav className="dory-navigation text-base lg:text-sm">
-            <ul role="list" className="space-y-9">
-                {currentTab && (
-                <li key={currentTab.title}>
-                    <h2 className="font-display font-medium text-xs">{currentTab.title}</h2>
-                    {currentTab.groups.map(group => (
-                        <div key={group.title}>
-                            <h3 className="mt-4 text-sm font-semibold">{group.title}</h3>
-                            <ul role="list" className="mt-2 space-y-2 border-l-2 border-border lg:mt-4 lg:space-y-4 lg:border-border">
-                                {group.pages.map((page) => {
-                                    const isActive = effectivePath === page.href;
-                                    return (
-                                        <li key={page.href} className="relative">
-                                            <Link
-                                                href={page.href}
-                                                className={classNames(
-                                                'block w-full pl-3.5 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',
-                                                {
-                                                    'font-semibold text-brand-foreground': isActive,
-                                                    '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': !isActive
-                                                },
-                                            )}>
-                                                {page.title}
-                                            </Link>
-                                        </li>
-                                    );
-                                })}
-                            </ul>
-                        </div>
-                    ))}
-                </li>
-                )}
-            </ul>
-        </nav>
-    );
+  return <DocsNavigationView groups={groups} activeHref={effectivePath} renderPageLink={renderPageLink}
+    versionLabel={versionLabel} versionSelect={versionSelect} languageSelect={languageSelect} />;
 }

package/src/components/notification.tsx

@@ -1,11 +1,10 @@
-import { toast } from '@clidey/ux';
-import { InfoIcon } from 'lucide-react';
+import { CatalogIcon, toast } from '@clidey/ux';
 
 export function useNotification() {
   return {
     showNotification: (message: string, description?: string) => {
       toast(message, {
-        icon: <InfoIcon className="h-4 w-4" />,
+        icon: <CatalogIcon name="info" className="h-4 w-4" />,
         description: description,
       });
     }

package/src/components/routes.tsx

@@ -1,26 +1,32 @@
 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 { ALL_PAGES, getNavigationForPath, pathFromFilename } from './store';
+import docsConfig from '../../docs/dory.json' with { type: 'json' };
+import type { DoryConfig } from '../types/config';
+import { contentScope } from '../utils/content-scope';
+import { NotFoundPage } from '@clidey/ux';
 
 
 export default function Routes() {
   const pathname = usePathname();
   const [, navigate] = useLocation();
+  const scope = contentScope(docsConfig as DoryConfig, pathname);
+  const isScopeRoot = pathname === '/' || (Boolean(scope.prefix) && pathname === scope.prefix);
 
   // Redirect root to the first page so the URL reflects the actual content
   useEffect(() => {
-    if (pathname === '/') {
-      const firstPage = ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href;
+    if (isScopeRoot) {
+      const firstPage = getNavigationForPath(pathname)[0]?.groups[0]?.pages[0]?.href;
       if (firstPage) navigate(firstPage, { replace: true });
     }
   }, [pathname]);
 
   const route = useMemo(() => {
     let targetPath = pathname;
-    if (pathname === '/') {
+    if (isScopeRoot) {
       const ssrRoute = typeof window !== 'undefined' ? window.__DORY_ROUTE__ : undefined;
-      targetPath = ssrRoute || ALL_NAVIGATION[0]?.groups[0]?.pages[0]?.href || pathname;
+      targetPath = (pathname === '/' ? ssrRoute : undefined) || getNavigationForPath(pathname)[0]?.groups[0]?.pages[0]?.href || pathname;
     }
 
     const entry = Object.entries(ALL_PAGES).find(([path]) => path === targetPath);
@@ -28,7 +34,7 @@ export default function Routes() {
 
     const [path, mod] = entry;
     return {
-      path: pathname === '/' ? '/' : pathFromFilename(path),
+      path: isScopeRoot ? pathname : pathFromFilename(path),
       component: (mod as any).default,
     };
   }, [pathname]);
@@ -36,19 +42,11 @@ export default function Routes() {
   // 404 — no MDX module for this path (even if it appears in navigation)
   if (!route && pathname !== '/') {
     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-muted-foreground 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>
+      <NotFoundPage
+        description={`The page ${pathname} does not exist.`}
+        onHome={() => navigate(getNavigationForPath(pathname)[0]?.groups[0]?.pages[0]?.href ?? '/')}
+        homeLabel="Go to home"
+      />
     );
   }
 

package/src/components/search-index.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { createSearchIndex } from './search-index';
+
+describe('createSearchIndex', () => {
+  it('keeps runtime locale indexes separate', async () => {
+    const english = createSearchIndex();
+    const french = createSearchIndex();
+    await english.add('docs/index.mdx', { title: 'Inventory' }, 'publish the app');
+    await french.add('docs/fr/index.mdx', { title: 'Inventaire' }, 'publier l’application');
+
+    expect(english.search('publish').map(item => item.url)).toEqual(['docs/index.mdx']);
+    expect(french.search('publish')).toEqual([]);
+    expect(french.search('publier').map(item => item.url)).toEqual(['docs/fr/index.mdx']);
+  });
+});

package/src/components/search-index.ts

@@ -1,54 +1,55 @@
-let searchIndex: any = null;
+/** A separate index lets the embedded viewer search only its authorized docs. */
+export function createSearchIndex() {
+    let searchIndex: any = null;
 
-async function getSearchIndex() {
-    if (!searchIndex) {
-        const { Document } = await import('flexsearch');
-        searchIndex = new Document({
-            tokenize: 'full',
-            document: {
-                id: 'url',
-                index: 'content',
-                store: ['title', 'pageTitle'],
-            },
-            context: {
-                resolution: 9,
-                depth: 2,
-                bidirectional: true
-            }
-        });
+    async function getSearchIndex() {
+        if (!searchIndex) {
+            const { Document } = await import('flexsearch');
+            searchIndex = new Document({
+                tokenize: 'full',
+                document: {
+                    id: 'url',
+                    index: 'content',
+                    store: ['title', 'pageTitle'],
+                },
+                context: {
+                    resolution: 9,
+                    depth: 2,
+                    bidirectional: true
+                }
+            });
+        }
+        return searchIndex;
     }
-    return searchIndex;
-}
 
-export async function addToSearchIndex(filename: string, data: any, content: string) {
-    try {
-        const index = await getSearchIndex();
-        index.add({
-            url: filename,
-            title: data.title || '',
-            content: content,
-            pageTitle: data.title
-        });
-    } catch (error) {
-        console.warn(`Failed to index ${filename}:`, error);
-    }
+    return {
+        async add(filename: string, data: { title?: string }, content: string) {
+            try {
+                const index = await getSearchIndex();
+                index.add({
+                    url: filename,
+                    title: data.title || '',
+                    content,
+                    pageTitle: data.title,
+                });
+            } catch (error) {
+                console.warn(`Failed to index ${filename}:`, error);
+            }
+        },
+        search(query: string, options = {}): Array<{ url: string; title: string; pageTitle: string }> {
+            if (!searchIndex) return [];
+            const result = searchIndex.search(query, { ...options, enrich: true }) as any[];
+            if (result.length === 0) return [];
+            return result[0].result.map((item: any) => ({
+                url: item.id as string,
+                title: item.doc?.title || '',
+                pageTitle: item.doc?.pageTitle || '',
+            }));
+        },
+    };
 }
 
-export function search(query: string, options = {}) {
-    if (!searchIndex) return [];
+const defaultIndex = createSearchIndex();
 
-    const result = searchIndex.search(query, {
-        ...options,
-        enrich: true,
-    }) as any[];
-
-    if (result.length === 0) {
-        return [];
-    }
-
-    return result[0].result.map((item: any) => ({
-        url: item.id,
-        title: item.doc?.title || '',
-        pageTitle: item.doc?.pageTitle || '',
-    }));
-}
+export const addToSearchIndex = defaultIndex.add;
+export const search = defaultIndex.search;