@raystack/chronicle 0.12.4 → 0.12.5

package/src/lib/mdx-error.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test';
+import { buildCodeFrame, parseMdxError } from './mdx-error';
+
+describe('parseMdxError', () => {
+  test('parses VFileMessage shape (parse errors, file.fail)', () => {
+    const info = parseMdxError({
+      reason: 'Unknown component <Foo> — available components: Callout',
+      line: 12,
+      column: 3,
+      file: '/project/.content/docs/setup.mdx',
+      message: 'ignored',
+    });
+    expect(info).toEqual({
+      message: 'Unknown component <Foo> — available components: Callout',
+      file: '/project/.content/docs/setup.mdx',
+      line: 12,
+      column: 3,
+    });
+  });
+
+  test('parses Rollup/Vite transform error shape', () => {
+    const info = parseMdxError({
+      message: 'Expected a closing tag for `<Callout>` (2:1-2:10)',
+      loc: { file: '/p/.content/docs/a.mdx', line: 2, column: 1 },
+    });
+    expect(info?.file).toBe('/p/.content/docs/a.mdx');
+    expect(info?.line).toBe(2);
+    expect(info?.column).toBe(1);
+  });
+
+  test('falls back to id + message-embedded position', () => {
+    const info = parseMdxError({
+      message: 'Unexpected closing tag `</div>`, expected corresponding opening tag (5:1-5:7)',
+      id: '/p/.content/docs/b.mdx',
+    });
+    expect(info?.file).toBe('/p/.content/docs/b.mdx');
+    expect(info?.line).toBe(5);
+    expect(info?.column).toBe(1);
+  });
+
+  test('strips vite query suffix from module ids', () => {
+    const info = parseMdxError({
+      message: 'boom at (1:1)',
+      id: '/p/.content/docs/c.mdx?collection=default',
+    });
+    expect(info?.file).toBe('/p/.content/docs/c.mdx');
+  });
+
+  test('detects MDX runtime missing-component errors', () => {
+    const info = parseMdxError(new Error('Expected component `Foo` to be defined: you likely forgot to import, pass, or provide it.'));
+    expect(info?.message).toContain('Unknown component <Foo>');
+  });
+
+  test('returns null for unrelated errors', () => {
+    expect(parseMdxError(new Error('connect ECONNREFUSED'))).toBeNull();
+    expect(parseMdxError({ message: 'fail', id: '/p/src/app.tsx' })).toBeNull();
+    expect(parseMdxError(null)).toBeNull();
+    expect(parseMdxError('string error')).toBeNull();
+  });
+});
+
+describe('buildCodeFrame', () => {
+  const source = 'one\ntwo\nthree\nfour\nfive\nsix';
+
+  test('includes context lines around the target', () => {
+    const frame = buildCodeFrame(source, 3, 2);
+    expect(frame.lines.map(l => l.number)).toEqual([1, 2, 3, 4, 5]);
+    expect(frame.lines.find(l => l.target)?.text).toBe('three');
+    expect(frame.caretColumn).toBe(2);
+  });
+
+  test('clamps at file boundaries', () => {
+    const first = buildCodeFrame(source, 1);
+    expect(first.lines.map(l => l.number)).toEqual([1, 2, 3]);
+    const last = buildCodeFrame(source, 6);
+    expect(last.lines.map(l => l.number)).toEqual([4, 5, 6]);
+  });
+});

package/src/lib/mdx-error.ts

@@ -0,0 +1,91 @@
+export interface MdxErrorInfo {
+  /** Human-readable reason, without file/position noise. */
+  message: string
+  /** Absolute path of the failing content file, when known. */
+  file?: string
+  line?: number
+  column?: number
+}
+
+export interface CodeFrame {
+  lines: Array<{ number: number; text: string; target: boolean }>
+  /** 1-based caret column on the target line, when known. */
+  caretColumn?: number
+}
+
+interface ErrorLike {
+  message?: string
+  reason?: string
+  file?: string
+  line?: number
+  column?: number
+  place?: { line?: number; column?: number; start?: { line?: number; column?: number } }
+  loc?: { file?: string; line?: number; column?: number }
+  id?: string
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: strips ANSI color codes
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g
+
+const isContentFile = (p?: string): p is string => !!p && /\.mdx?$/.test(p.split('?')[0])
+
+function cleanMessage(raw: string): string {
+  const lines = raw
+    .replace(ANSI_PATTERN, '')
+    .split('\n')
+    .map(line =>
+      line
+        .replace(/^\[(?:plugin|vite)[^\]]*\]\s*/, '')
+        .replace(/^\S*\.mdx?(?::[\d:-]+)*:?\s*/, '')
+        .trim(),
+    )
+    .filter(line => line && !/^Build failed with \d+ errors?:?$/.test(line))
+  return lines[0] ?? raw.trim()
+}
+
+/**
+ * Extracts file/position info from the various error shapes an MDX failure
+ * can surface as: a VFileMessage (parse errors, remark plugin `file.fail`),
+ * a Rollup/Vite transform error (`loc`/`id`), or MDX's runtime
+ * `_missingMdxReference` throw. Returns null for errors unrelated to MDX.
+ */
+export function parseMdxError(err: unknown): MdxErrorInfo | null {
+  if (!err || typeof err !== 'object') return null
+  const e = err as ErrorLike
+  const rawMessage = e.reason || e.message || ''
+
+  // MDX runtime: unknown component reached rendering (no file context available)
+  const missing = rawMessage.match(/Expected component `([^`]+)` to be defined/)
+  if (missing) {
+    return { message: `Unknown component <${missing[1]}> — it is not registered in Chronicle's MDX components.` }
+  }
+
+  const file = [e.file, e.loc?.file, e.id, ...(rawMessage.match(/((?:\/|\.\.?\/)[^\s:]+\.mdx?)/) ?? [])]
+    .find(isContentFile)
+  if (!file) return null
+
+  const place = e.place?.start ?? e.place
+  let line = e.line ?? place?.line ?? e.loc?.line
+  let column = e.column ?? place?.column ?? e.loc?.column
+  if (line == null) {
+    // Fall back to `12:3` or `12:3-14:1` position embedded in the message text
+    const pos = rawMessage.match(/(\d+):(\d+)(?:-\d+:\d+)?/)
+    if (pos) {
+      line = Number(pos[1])
+      column = Number(pos[2])
+    }
+  }
+
+  return { message: cleanMessage(rawMessage), file: file.split('?')[0], line, column }
+}
+
+export function buildCodeFrame(source: string, line: number, column?: number, context = 2): CodeFrame {
+  const all = source.split(/\r?\n/)
+  const start = Math.max(1, line - context)
+  const end = Math.min(all.length, line + context)
+  const lines = []
+  for (let n = start; n <= end; n++) {
+    lines.push({ number: n, text: all[n - 1] ?? '', target: n === line })
+  }
+  return { lines, caretColumn: column }
+}

package/src/lib/openapi.ts

@@ -95,7 +95,7 @@ function deepResolveRefs(
   return result
 }
 
-function resolveDocument(doc: OpenAPIV3.Document): OpenAPIV3.Document {
+export function resolveDocument(doc: OpenAPIV3.Document): OpenAPIV3.Document {
   const root = doc as unknown as JsonObject
   return deepResolveRefs(doc, root) as unknown as OpenAPIV3.Document
 }

package/src/lib/page-context.tsx

@@ -7,9 +7,11 @@ import {
   useRef,
   useState
 } from 'react';
-import { useLocation } from 'react-router';
+import { useLocation, useNavigate } from 'react-router';
 import type { ApiSpec } from '@/lib/openapi';
-import { resolveRoute, RouteType } from '@/lib/route-resolver';
+import { resolveRoute, resolveContentRootRedirect, RouteType } from '@/lib/route-resolver';
+import { isStaticMode } from '@/lib/static-mode';
+import { pageDataUrl, specsUrl } from '@/lib/data-urls';
 import type { VersionContext } from '@/lib/version-source';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 import type { ChronicleConfig, Frontmatter, Page, PageNavLink, Root, TableOfContents } from '@/types';
@@ -24,6 +26,8 @@ interface PageContextValue {
   page: Page | null;
   isLoading: boolean;
   errorStatus: number | null;
+  /** Render/load failure detail (e.g. MDX compile error) — non-status errors only. */
+  errorMessage: string | null;
   apiSpecs: ApiSpec[];
   version: VersionContext;
 }
@@ -43,6 +47,7 @@ export function usePageContext(): PageContextValue {
       page: null,
       isLoading: false,
       errorStatus: null,
+      errorMessage: null,
       apiSpecs: [],
       version: LATEST_CONTEXT,
     };
@@ -60,10 +65,6 @@ interface PageProviderProps {
   children: ReactNode;
 }
 
-function isApisRoute(pathname: string): boolean {
-  return pathname === '/apis' || pathname.startsWith('/apis/');
-}
-
 function getInitialErrorStatus(page: Page | null, config: ChronicleConfig, pathname: string): number | null {
   if (page) return null;
   const route = resolveRoute(pathname, config);
@@ -83,9 +84,11 @@ export function PageProvider({
   children
 }: PageProviderProps) {
   const { pathname } = useLocation();
+  const navigate = useNavigate();
   const [tree] = useState<Root>(initialTree);
   const [page, setPage] = useState<Page | null>(initialPage);
   const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, initialConfig, pathname));
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
   const [version, setVersion] = useState<VersionContext>(initialVersion);
   const [isLoading, setIsLoading] = useState(false);
@@ -94,10 +97,8 @@ export function PageProvider({
   const fetchApiSpecs = useCallback(async (route: { version: VersionContext }, cancelled: { current: boolean }) => {
     setIsLoading(true);
     try {
-      const specsUrl = route.version.dir
-        ? `/api/specs?version=${encodeURIComponent(route.version.dir)}`
-        : '/api/specs';
-      const res = await fetch(specsUrl);
+      const url = specsUrl(route.version.dir);
+      const res = await fetch(url);
       const specs = await res.json();
       if (!cancelled.current) setApiSpecs(specs);
     } catch {
@@ -118,7 +119,7 @@ export function PageProvider({
 
   const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
     const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
-    const apiPath = key ? `/api/page?slug=${key}` : '/api/page';
+    const apiPath = pageDataUrl(slug);
     return queryClient.fetchQuery({
       queryKey: ['pageData', key],
       queryFn: async () => {
@@ -143,6 +144,7 @@ export function PageProvider({
       const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
       if (cancelled.current) return;
       setErrorStatus(null);
+      setErrorMessage(null);
       setPage({
         slug,
         frontmatter: data.frontmatter,
@@ -153,9 +155,11 @@ export function PageProvider({
       });
     } catch (err) {
       if (cancelled.current) return;
-      const status = Number((err as Error).message) || 500;
+      const raw = (err as Error).message;
+      const status = Number(raw) || 500;
       setPage(null);
       setErrorStatus(status);
+      setErrorMessage(Number(raw) ? null : raw);
     } finally {
       if (!cancelled.current) setIsLoading(false);
     }
@@ -173,6 +177,7 @@ export function PageProvider({
     if (route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage) {
       setPage(null);
       setErrorStatus(null);
+      setErrorMessage(null);
       fetchApiSpecs(route, cancelled);
       return () => { cancelled.current = true; };
     }
@@ -180,18 +185,28 @@ export function PageProvider({
     if (route.type !== RouteType.DocsPage) {
       setPage(null);
       setErrorStatus(null);
+      setErrorMessage(null);
       return () => { cancelled.current = true; };
     }
 
+    if (isStaticMode()) {
+      const redirect = resolveContentRootRedirect(route.slug, initialConfig);
+      if (redirect) {
+        navigate(redirect, { replace: true });
+        return () => { cancelled.current = true; };
+      }
+    }
+
     setPage(null);
     setErrorStatus(null);
+    setErrorMessage(null);
     loadDocsPage(route.slug, cancelled);
     return () => { cancelled.current = true; };
-  }, [pathname, initialConfig, fetchApiSpecs, loadDocsPage]);
+  }, [pathname, initialConfig, fetchApiSpecs, loadDocsPage, navigate]);
 
   return (
     <PageContext.Provider
-      value={{ config: initialConfig, tree, page, isLoading, errorStatus, apiSpecs, version }}
+      value={{ config: initialConfig, tree, page, isLoading, errorStatus, errorMessage, apiSpecs, version }}
     >
       {children}
     </PageContext.Provider>

package/src/lib/preload.ts

@@ -1,4 +1,6 @@
 import { QueryClient } from '@tanstack/react-query';
+import { isStaticMode } from '@/lib/static-mode';
+import { pageDataUrl } from '@/lib/data-urls';
 
 export const queryClient = new QueryClient({
   defaultOptions: {
@@ -17,8 +19,7 @@ export function pageDataQueryKey(pathname: string) {
 
 async function fetchPageDataByPathname(pathname: string) {
   const slug = pathname.split('/').filter(Boolean);
-  const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
-  const apiPath = key ? `/api/page?slug=${key}` : '/api/page';
+  const apiPath = pageDataUrl(slug);
   const res = await fetch(apiPath);
   if (!res.ok) throw new Error(String(res.status));
   return res.json();
@@ -42,6 +43,7 @@ export function prefetchPageData(pathname: string) {
 }
 
 export function prefetchSearchSuggestions() {
+  if (isStaticMode()) return;
   queryClient.prefetchQuery({
     queryKey: ['search', '', undefined],
     queryFn: async () => {

package/src/lib/remark-validate-mdx.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test';
+import type { Root } from 'mdast';
+import { VFile } from 'vfile';
+import remarkValidateMdxPlugin, { type RemarkValidateMdxOptions } from './remark-validate-mdx';
+
+const remarkValidateMdx = remarkValidateMdxPlugin as unknown as (
+  options?: RemarkValidateMdxOptions,
+) => (tree: Root, file: VFile) => void;
+
+const position = {
+  start: { line: 3, column: 1, offset: 10 },
+  end: { line: 3, column: 10, offset: 19 },
+};
+
+function jsxNode(name: string | null, type = 'mdxJsxFlowElement') {
+  return { type, name, attributes: [], children: [], position } as unknown as Root['children'][number];
+}
+
+function importNode(localName: string) {
+  return {
+    type: 'mdxjsEsm',
+    value: `import ${localName} from './x'`,
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ImportDeclaration',
+            specifiers: [{ type: 'ImportDefaultSpecifier', local: { name: localName } }],
+          },
+        ],
+      },
+    },
+  } as unknown as Root['children'][number];
+}
+
+function run(children: Root['children']) {
+  const tree: Root = { type: 'root', children };
+  const file = new VFile({ path: '/project/.content/docs/test.mdx' });
+  remarkValidateMdx()(tree, file);
+}
+
+describe('remarkValidateMdx', () => {
+  test('fails on unknown capitalized component', () => {
+    expect(() => run([jsxNode('Foo')])).toThrow(/Unknown component <Foo>/);
+  });
+
+  test('reports position of the offending node', () => {
+    try {
+      run([jsxNode('Foo')]);
+      throw new Error('expected failure');
+    } catch (err) {
+      expect((err as { line?: number }).line).toBe(3);
+      expect((err as { column?: number }).column).toBe(1);
+    }
+  });
+
+  test('allows registered components', () => {
+    expect(() => run([jsxNode('Callout'), jsxNode('Mermaid')])).not.toThrow();
+  });
+
+  test('allows member expressions on registered components', () => {
+    expect(() => run([jsxNode('Tabs.Tab'), jsxNode('Tabs.Content', 'mdxJsxTextElement')])).not.toThrow();
+  });
+
+  test('fails on member expressions with unknown root', () => {
+    expect(() => run([jsxNode('Foo.Bar')])).toThrow(/Unknown component <Foo.Bar>/);
+  });
+
+  test('fails on unknown lowercase tag', () => {
+    expect(() => run([jsxNode('foox')])).toThrow(/Unknown HTML tag <foox>/);
+  });
+
+  test('allows standard HTML and SVG tags', () => {
+    expect(() => run([jsxNode('div'), jsxNode('details'), jsxNode('clipPath'), jsxNode('svg')])).not.toThrow();
+  });
+
+  test('allows custom elements with a dash', () => {
+    expect(() => run([jsxNode('my-widget')])).not.toThrow();
+  });
+
+  test('allows fragments', () => {
+    expect(() => run([jsxNode(null)])).not.toThrow();
+  });
+
+  test('allows components imported within the MDX file', () => {
+    expect(() => run([importNode('Chart'), jsxNode('Chart')])).not.toThrow();
+  });
+
+  test('respects custom components option', () => {
+    const tree: Root = { type: 'root', children: [jsxNode('Special')] };
+    const file = new VFile({ path: '/t.mdx' });
+    expect(() => remarkValidateMdx({ components: ['Special'] })(tree, file)).not.toThrow();
+  });
+});

package/src/lib/remark-validate-mdx.ts

@@ -0,0 +1,85 @@
+import type { Root } from 'mdast'
+import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx-jsx'
+import type { Plugin } from 'unified'
+import type { Node } from 'unist'
+import { visit } from 'unist-util-visit'
+import type { VFile } from 'vfile'
+import { KNOWN_TAGS, MDX_COMPONENT_NAMES } from './mdx-component-names'
+import { MdxNodeType } from './mdx-utils'
+
+export interface RemarkValidateMdxOptions {
+  /** Custom component names allowed in MDX content. Defaults to MDX_COMPONENT_NAMES. */
+  components?: readonly string[]
+}
+
+interface EstreeNode {
+  type: string
+  specifiers?: Array<{ local?: { name?: string } }>
+  declaration?: EstreeNode | null
+  declarations?: Array<{ id?: { name?: string } }>
+  id?: { name?: string }
+  body?: EstreeNode[]
+}
+
+/** Names declared by import/export statements inside the MDX file itself. */
+function collectLocalNames(tree: Root): Set<string> {
+  const names = new Set<string>()
+  visit(tree, 'mdxjsEsm', (node: Node) => {
+    const program = (node as Node & { data?: { estree?: EstreeNode } }).data?.estree
+    for (const stmt of program?.body ?? []) {
+      if (stmt.type === 'ImportDeclaration') {
+        for (const spec of stmt.specifiers ?? []) {
+          if (spec.local?.name) names.add(spec.local.name)
+        }
+      }
+      const decl = stmt.type === 'ExportNamedDeclaration' ? stmt.declaration : stmt
+      if (!decl) continue
+      if (decl.type === 'VariableDeclaration') {
+        for (const d of decl.declarations ?? []) {
+          if (d.id?.name) names.add(d.id.name)
+        }
+      } else if ((decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') && decl.id?.name) {
+        names.add(decl.id.name)
+      }
+    }
+  })
+  return names
+}
+
+/**
+ * Fails compilation with a precise message (file, line, column) when MDX
+ * content uses a component that is neither a standard HTML/SVG element,
+ * a registered Chronicle component, nor imported/defined in the file.
+ * Unclosed or mismatched tags are already rejected earlier by the MDX parser.
+ */
+const remarkValidateMdx: Plugin<[RemarkValidateMdxOptions?], Root> = (options = {}) => {
+  const allowed = new Set<string>(options.components ?? MDX_COMPONENT_NAMES)
+
+  return (tree, file: VFile) => {
+    const locals = collectLocalNames(tree)
+
+    visit(tree, [MdxNodeType.JsxFlow, MdxNodeType.JsxText], (node) => {
+      const { name, position } = node as MdxJsxFlowElement | MdxJsxTextElement
+      if (!name) return // fragment <>...</>
+
+      const root = name.split('.')[0]
+      if (root.includes('-')) return // custom elements like <my-widget>
+      if (locals.has(root)) return
+
+      if (/^[a-z]/.test(root)) {
+        if (KNOWN_TAGS.has(root)) return
+        file.fail(
+          `Unknown HTML tag <${name}> — not a standard HTML/SVG element. If it is a custom component, register it in Chronicle's MDX components.`,
+          position,
+        )
+      } else if (!allowed.has(root)) {
+        file.fail(
+          `Unknown component <${name}> — available components: ${[...allowed].join(', ')}. Import it in this file or register it in Chronicle's MDX components.`,
+          position,
+        )
+      }
+    })
+  }
+}
+
+export default remarkValidateMdx

package/src/lib/route-resolver.ts

@@ -81,3 +81,10 @@ export function resolveRoute(
 
   return { type: RouteType.DocsPage, version, slug: parts }
 }
+
+export function resolveContentRootRedirect(slug: string[], config: ChronicleConfig): string | null {
+  if (slug.length !== 1) return null;
+  const entry = config.content?.find(c => c.dir === slug[0]);
+  if (entry?.index_page) return `/${entry.dir}/${entry.index_page}`;
+  return null;
+}

package/src/lib/static-mode.ts

@@ -0,0 +1,3 @@
+export function isStaticMode(): boolean {
+  return typeof window !== 'undefined' && (window as unknown as Record<string, unknown>).__STATIC_MODE__ === true;
+}

package/src/pages/DocsPage.tsx

@@ -4,6 +4,7 @@ import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { resolveDocsRedirect } from '@/lib/tree-utils';
 import { NotFound } from '@/pages/NotFound';
+import { RenderError } from '@/pages/RenderError';
 import { getTheme } from '@/themes/registry';
 
 interface DocsPageProps {
@@ -11,7 +12,7 @@ interface DocsPageProps {
 }
 
 export function DocsPage({ slug }: DocsPageProps) {
-  const { config, tree, page, isLoading, errorStatus } = usePageContext();
+  const { config, tree, page, isLoading, errorStatus, errorMessage } = usePageContext();
 
   if (errorStatus === StatusCodes.NOT_FOUND) {
     const contentConfig = config.content?.find(c => c.dir === slug[0]);
@@ -19,7 +20,7 @@ export function DocsPage({ slug }: DocsPageProps) {
     if (redirectUrl) return <Navigate to={redirectUrl} replace />;
     return <NotFound />;
   }
-  if (errorStatus) return <NotFound />;
+  if (errorStatus) return <RenderError message={errorMessage} />;
   const { Page, Skeleton } = getTheme(config.theme?.name);
 
   if (isLoading || !page) return <Skeleton />;

package/src/pages/NotFound.module.css

@@ -1,3 +1,13 @@
 .emptyState {
   justify-content: center;
 }
+
+.errorDetail {
+  max-width: 640px;
+  margin: 0;
+  white-space: pre-wrap;
+  text-align: left;
+  font-family: var(--rs-font-mono);
+  font-size: var(--rs-font-size-small);
+  color: var(--rs-color-foreground-base-secondary);
+}

package/src/pages/RenderError.tsx

@@ -0,0 +1,18 @@
+import { ExclamationTriangleIcon } from '@heroicons/react/24/outline';
+import { EmptyState } from '@raystack/apsara';
+import styles from './NotFound.module.css';
+
+export function RenderError({ message }: { message: string | null }) {
+  return (
+    <EmptyState
+      icon={<ExclamationTriangleIcon width={32} height={32} />}
+      heading="Failed to render page"
+      subHeading={
+        message
+          ? <pre className={styles.errorDetail}>{message}</pre>
+          : 'Something went wrong while rendering this page.'
+      }
+      classNames={{ container: styles.emptyState }}
+    />
+  );
+}

package/src/server/App.tsx

@@ -4,6 +4,7 @@ import { ThemeProvider, Skeleton, Flex } from '@raystack/apsara';
 import { lazy, Suspense } from 'react';
 import { Navigate, useLocation } from 'react-router';
 import { AnalyticsProvider } from '@/components/analytics/AnalyticsProvider';
+import { SearchDialog, SearchProvider } from '@/components/ui/search';
 import { usePageContext } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import type { ChronicleConfig } from '@/types';
@@ -38,18 +39,21 @@ export function App() {
       forcedTheme={themeConfig.forcedTheme}
     >
       <AnalyticsProvider config={config.analytics ?? { enabled: false }} appName={config.site.title}>
-        <RootHead config={config} />
-        <Suspense fallback={<PageFallback />}>
-          {isApi ? (
-            <ApiLayout>
-              <ApiPage slug={apiSlug} />
-            </ApiLayout>
-          ) : (
-            <DocsLayout hideSidebar={isLanding}>
-              {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
-            </DocsLayout>
-          )}
-        </Suspense>
+        <SearchProvider>
+          <RootHead config={config} />
+          {config.search?.enabled && <SearchDialog />}
+          <Suspense fallback={<PageFallback />}>
+            {isApi ? (
+              <ApiLayout>
+                <ApiPage slug={apiSlug} />
+              </ApiLayout>
+            ) : (
+              <DocsLayout hideSidebar={isLanding}>
+                {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
+              </DocsLayout>
+            )}
+          </Suspense>
+        </SearchProvider>
       </AnalyticsProvider>
     </ThemeProvider>
   );