@raystack/chronicle 0.12.3 → 0.12.5

package/src/server/api/apis-proxy.ts

@@ -1,7 +1,11 @@
 import { defineHandler, HTTPError } from 'nitro';
+import { StatusCodes } from 'http-status-codes';
 import { loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 
+const MAX_BODY_SIZE = 10_485_760; // 10 MB
+const UPSTREAM_TIMEOUT_MS = 120_000;
+
 interface ProxyRequest {
   specName: string;
   method: string;
@@ -10,9 +14,26 @@ interface ProxyRequest {
   body?: unknown;
 }
 
+function isPathSafe(p: string): boolean {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(p);
+  } catch {
+    return false;
+  }
+  if (/^[a-z]+:\/\//i.test(decoded)) return false;
+  const normalized = new URL(decoded, 'http://localhost').pathname;
+  return !normalized.split('/').includes('..');
+}
+
 export default defineHandler(async event => {
   if (event.req.method !== 'POST') {
-    throw new HTTPError({ status: 405, message: 'Method not allowed' });
+    throw new HTTPError({ status: StatusCodes.METHOD_NOT_ALLOWED, message: 'Method not allowed' });
+  }
+
+  const contentLength = parseInt(event.req.headers.get('content-length') ?? '0', 10);
+  if (contentLength > MAX_BODY_SIZE) {
+    throw new HTTPError({ status: StatusCodes.CONTENT_TOO_LARGE, message: `Request body too large (max ${MAX_BODY_SIZE} bytes)` });
   }
 
   const { specName, method, path, headers, body } =
@@ -20,7 +41,7 @@ export default defineHandler(async event => {
 
   if (!specName || !method || !path) {
     throw new HTTPError({
-      status: 400,
+      status: StatusCodes.BAD_REQUEST,
       message: 'Missing specName, method, or path'
     });
   }
@@ -30,11 +51,11 @@ export default defineHandler(async event => {
   const spec = specs.find(s => s.name === specName);
 
   if (!spec) {
-    throw new HTTPError({ status: 404, message: `Unknown spec: ${specName}` });
+    throw new HTTPError({ status: StatusCodes.NOT_FOUND, message: `Unknown spec: ${specName}` });
   }
 
-  if (/^[a-z]+:\/\//i.test(path) || path.includes('..')) {
-    throw new HTTPError({ status: 400, message: 'Invalid path' });
+  if (!isPathSafe(path)) {
+    throw new HTTPError({ status: StatusCodes.BAD_REQUEST, message: 'Invalid path' });
   }
 
   const url = spec.server.url + path;
@@ -43,7 +64,8 @@ export default defineHandler(async event => {
     const response = await fetch(url, {
       method,
       headers,
-      body: body ? JSON.stringify(body) : undefined
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
     });
 
     const contentType = response.headers.get('content-type') ?? '';
@@ -64,12 +86,15 @@ export default defineHandler(async event => {
       headers: responseHeaders
     });
   } catch (error) {
+    if (error instanceof DOMException && error.name === 'TimeoutError') {
+      throw new HTTPError({ status: StatusCodes.GATEWAY_TIMEOUT, message: `Upstream request timed out after ${UPSTREAM_TIMEOUT_MS}ms` });
+    }
     const message =
       error instanceof Error
         ? `${error.message}${error.cause ? `: ${(error.cause as Error).message}` : ''}`
         : 'Request failed';
     throw new HTTPError({
-      status: 502,
+      status: StatusCodes.BAD_GATEWAY,
       message: `Could not reach ${url}\n${message}`
     });
   }

package/src/server/dev-error-page.ts

@@ -0,0 +1,133 @@
+import { buildCodeFrame, type CodeFrame, parseMdxError } from '@/lib/mdx-error'
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+function displayPath(file: string): string {
+  const roots = [
+    typeof __CHRONICLE_CONTENT_DIR__ !== 'undefined' ? __CHRONICLE_CONTENT_DIR__ : '',
+    typeof __CHRONICLE_PROJECT_ROOT__ !== 'undefined' ? __CHRONICLE_PROJECT_ROOT__ : '',
+  ]
+  for (const root of roots) {
+    if (root && file.startsWith(root)) return file.slice(root.length).replace(/^\//, '')
+  }
+  return file
+}
+
+function frameHtml(frame: CodeFrame): string {
+  const gutter = String(frame.lines[frame.lines.length - 1]?.number ?? 0).length
+  const rows = frame.lines.flatMap(({ number, text, target }) => {
+    const row = `<div class="row${target ? ' target' : ''}"><span class="ln">${target ? '&gt;' : ' '} ${String(number).padStart(gutter)}</span><span class="src">${escapeHtml(text)}</span></div>`
+    if (target && frame.caretColumn) {
+      return [row, `<div class="row caret"><span class="ln">${' '.repeat(gutter + 1)}</span><span class="src">${' '.repeat(frame.caretColumn - 1)}^</span></div>`]
+    }
+    return [row]
+  })
+  return `<pre class="frame">${rows.join('')}</pre>`
+}
+
+/**
+ * Dev-only: renders a styled error page for MDX failures (syntax errors,
+ * unknown components) naming the file, position, and a source code frame.
+ * Returns null when the error is not MDX-related.
+ */
+export async function renderMdxErrorResponse(err: unknown): Promise<Response | null> {
+  const info = parseMdxError(err)
+  if (!info) return null
+
+  let frame: CodeFrame | null = null
+  if (info.file && info.line) {
+    try {
+      const fs = await import('node:fs/promises')
+      frame = buildCodeFrame(await fs.readFile(info.file, 'utf-8'), info.line, info.column)
+    } catch {
+      // source not readable — show the message without a code frame
+    }
+  }
+
+  const location = info.file
+    ? `${displayPath(info.file)}${info.line ? `:${info.line}${info.column ? `:${info.column}` : ''}` : ''}`
+    : null
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MDX Error</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body {
+      margin: 0; padding: 48px 24px;
+      font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+      background: #fff; color: #18181b;
+    }
+    .card { max-width: 860px; margin: 0 auto; }
+    .badge {
+      display: inline-block; padding: 4px 10px; border-radius: 6px;
+      background: #dc2626; color: #fff; font-size: 12px; font-weight: 600;
+      letter-spacing: 0.04em; text-transform: uppercase;
+    }
+    h1 { font-size: 20px; line-height: 1.5; margin: 16px 0 8px; }
+    .loc {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 13px; color: #71717a; margin-bottom: 24px;
+    }
+    .frame {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 13px; line-height: 1.7; overflow-x: auto;
+      background: #fafafa; border: 1px solid #e4e4e7; border-radius: 8px;
+      padding: 12px 0; margin: 0;
+    }
+    .row { display: flex; white-space: pre; }
+    .row .ln {
+      flex: none; padding: 0 12px; color: #a1a1aa;
+      border-right: 1px solid #e4e4e7; margin-right: 12px; user-select: none;
+    }
+    .row.target { background: rgba(220, 38, 38, 0.08); }
+    .row.target .ln, .row.caret .src { color: #dc2626; font-weight: 600; }
+    .hint { font-size: 13px; color: #71717a; margin-top: 24px; }
+    @media (prefers-color-scheme: dark) {
+      body { background: #09090b; color: #f4f4f5; }
+      .frame { background: #18181b; border-color: #27272a; }
+      .row .ln { border-color: #27272a; color: #52525b; }
+      .loc, .hint { color: #a1a1aa; }
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <span class="badge">MDX Error</span>
+    <h1>${escapeHtml(info.message)}</h1>
+    ${location ? `<div class="loc">${escapeHtml(location)}</div>` : ''}
+    ${frame ? frameHtml(frame) : ''}
+    <p class="hint">Fix the file and save — the page reloads automatically.</p>
+  </div>
+  <script>
+    (function poll(last) {
+      setTimeout(async () => {
+        try {
+          const res = await fetch(location.href, { headers: { accept: 'text/html' } });
+          if (res.ok) return location.reload();
+          const body = await res.text();
+          if (last !== null && body !== last) return location.reload();
+          poll(body);
+        } catch {
+          poll(last);
+        }
+      }, 1000);
+    })(null);
+  </script>
+</body>
+</html>`
+
+  return new Response(html, {
+    status: 500,
+    headers: { 'Content-Type': 'text/html;charset=utf-8' },
+  })
+}

package/src/server/entry-server.tsx

@@ -193,6 +193,7 @@ export default {
         </body>
       </html>,
     );
+    await stream.allReady;
 
     const renderDuration = performance.now() - renderStart;
 
@@ -207,6 +208,11 @@ export default {
     });
     } catch (err) {
       console.error(`[chronicle] SSR error for ${pathname}:`, err);
+      if (import.meta.env.DEV) {
+        const { renderMdxErrorResponse } = await import('./dev-error-page');
+        const mdxError = await renderMdxErrorResponse(err);
+        if (mdxError) return mdxError;
+      }
       return errorResponse(500, 'Internal Server Error', err instanceof Error ? err.message : String(err));
     }
   },

package/src/server/entry-static.tsx

@@ -0,0 +1,151 @@
+import '@vitejs/plugin-react/preamble';
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { mdxComponents } from '@/components/mdx';
+import { getApiConfigsForVersion } from '@/lib/config';
+import { PageProvider } from '@/lib/page-context';
+import { queryClient } from '@/lib/preload';
+import { resolveRoute, resolveContentRootRedirect, RouteType } from '@/lib/route-resolver';
+import { pageDataUrl, specsUrl } from '@/lib/data-urls';
+import { resolveVersionFromUrl, type VersionContext } from '@/lib/version-source';
+import type { ChronicleConfig, Frontmatter, PageNavLink, Root, TableOfContents } from '@/types';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ReactNode } from 'react';
+import { App } from './App';
+
+interface StaticEmbeddedData {
+  config: ChronicleConfig;
+  tree: Root;
+  version: VersionContext;
+}
+
+const defaultConfig: ChronicleConfig = {
+  site: { title: 'Documentation' },
+  content: [{ dir: 'docs', label: 'Docs' }],
+};
+
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any>; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+async function loadMdxModule(relativePath: string): Promise<{ content: ReactNode; toc: TableOfContents }> {
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  if (!loader) return { content: null, toc: [] };
+  const mod = await loader();
+  const content = mod.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+  return { content, toc: mod.toc ?? [] };
+}
+
+async function fetchStaticPageData(slug: string[]) {
+  const res = await fetch(pageDataUrl(slug));
+  if (!res.ok) throw new Error(String(res.status));
+  const ct = res.headers.get('content-type') ?? '';
+  if (!ct.includes('json')) throw new Error('404');
+  return res.json();
+}
+
+async function fetchStaticApiSpecs(version: VersionContext): Promise<ApiSpec[]> {
+  try {
+    const res = await fetch(specsUrl(version.dir));
+    if (!res.ok) return [];
+    const ct = res.headers.get('content-type') ?? '';
+    if (!ct.includes('json')) return [];
+    return res.json();
+  } catch {
+    return [];
+  }
+}
+
+async function mount() {
+  try {
+    const embedded = (
+      window as unknown as { __PAGE_DATA__?: StaticEmbeddedData }
+    ).__PAGE_DATA__;
+
+    const config: ChronicleConfig = embedded?.config ?? defaultConfig;
+    const tree: Root = embedded?.tree ?? { name: 'root', children: [] };
+
+    const route = resolveRoute(window.location.pathname, config);
+
+    if (route.type === RouteType.Redirect) {
+      window.location.replace(route.to);
+      return;
+    }
+
+    if (route.type === RouteType.DocsPage) {
+      const redirect = resolveContentRootRedirect(route.slug, config);
+      if (redirect) {
+        window.location.replace(redirect);
+        return;
+      }
+    }
+
+    const routeVersion: VersionContext = resolveVersionFromUrl(
+      window.location.pathname,
+      config,
+    );
+    const version: VersionContext = embedded?.version ?? routeVersion;
+
+    const isApiRoute =
+      route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage;
+    const apiConfigs = isApiRoute
+      ? getApiConfigsForVersion(config, routeVersion.dir)
+      : [];
+    const apiSpecs: ApiSpec[] = apiConfigs.length
+      ? await fetchStaticApiSpecs(routeVersion)
+      : [];
+
+    let page = null;
+    if (route.type === RouteType.DocsPage) {
+      try {
+        const data = await fetchStaticPageData(route.slug);
+        const mdxPath = data.originalPath || data.relativePath;
+        if (mdxPath && data.frontmatter) {
+          const { content, toc } = await loadMdxModule(mdxPath);
+          page = {
+            slug: route.slug,
+            frontmatter: data.frontmatter as Frontmatter,
+            prev: (data.prev as PageNavLink) ?? null,
+            next: (data.next as PageNavLink) ?? null,
+            content,
+            toc,
+          };
+        }
+      } catch {
+        // page will remain null, context will show 404
+      }
+    }
+
+    createRoot(document.getElementById('root')!).render(
+      <QueryClientProvider client={queryClient}>
+        <BrowserRouter>
+          <ReactRouterProvider>
+            <PageProvider
+              initialConfig={config}
+              initialTree={tree}
+              initialPage={page}
+              initialApiSpecs={apiSpecs}
+              initialVersion={version}
+              loadMdx={loadMdxModule}
+            >
+              <App />
+            </PageProvider>
+          </ReactRouterProvider>
+        </BrowserRouter>
+      </QueryClientProvider>
+    );
+  } catch (err) {
+    console.error('Static mount failed:', err);
+  }
+}
+
+mount();

package/src/server/error.ts

@@ -1,9 +1,21 @@
 import { defineErrorHandler, HTTPError } from 'nitro';
 
-export default defineErrorHandler((error, _event) => {
+export default defineErrorHandler(async (error, _event) => {
   const status = HTTPError.isError(error) ? error.status : 500;
   const message = error.message || 'Internal Server Error';
 
+  // MDX failures in content (syntax errors, unknown components) surface here:
+  // the eager frontmatter glob in source.ts compiles every content file at
+  // module load, before the SSR fetch handler can catch anything.
+  if (import.meta.env.DEV) {
+    const { renderMdxErrorResponse } = await import('./dev-error-page');
+    const candidates = [error, (error as { cause?: unknown }).cause];
+    for (const candidate of candidates) {
+      const response = candidate ? await renderMdxErrorResponse(candidate) : null;
+      if (response) return response;
+    }
+  }
+
   return new Response(JSON.stringify({ error: true, status, message }), {
     status,
     headers: { 'Content-Type': 'application/json' },

package/src/server/plugins/telemetry.ts

@@ -82,7 +82,8 @@ export default definePlugin((nitroApp) => {
   })
 
   nitroApp.hooks.hook('chronicle:ssr-rendered', (route, status, durationMs) => {
-    ssrRenderDuration.record(durationMs, { route: toEndpoint(route), status })
+    const endpoint = status === 404 ? '/api/not-found' : toEndpoint(route)
+    ssrRenderDuration.record(durationMs, { route: endpoint, status })
   })
 
   nitroApp.hooks.hook('request', (event) => {
@@ -95,7 +96,7 @@ export default definePlugin((nitroApp) => {
     const duration = performance.now() - start
     const method = event.req.method
     const route = new URL(event.req.url).pathname
-    const endpoint = toEndpoint(route)
+    const endpoint = res.status === 404 ? '/api/not-found' : toEndpoint(route)
 
     const clientIp =
       event.req.headers['x-forwarded-for']?.toString().split(',')[0].trim() ??

package/src/server/vite-config.ts

@@ -11,6 +11,7 @@ import remarkResolveImages from '../lib/remark-resolve-images';
 import remarkResolveLinks from '../lib/remark-resolve-links';
 import remarkReadingTime from 'remark-reading-time';
 import remarkUnusedDirectives from '../lib/remark-unused-directives';
+import remarkValidateMdx from '../lib/remark-validate-mdx';
 
 function getDatabaseConnector(preset?: string): { connector: string; options?: Record<string, unknown> } {
   switch (preset) {
@@ -27,7 +28,7 @@ function getDatabaseConnector(preset?: string): { connector: string; options?: R
 
 const STATIC_PRESETS = new Set(['static', 'vercel-static', 'cloudflare-pages', 'github-pages']);
 
-function isStaticPreset(preset?: string): boolean {
+export function isStaticPreset(preset?: string): boolean {
   return !!preset && STATIC_PRESETS.has(preset);
 }
 
@@ -72,8 +73,9 @@ export async function createViteConfig(
     plugins: [
       nitro({
         serverDir: path.resolve(packageRoot, 'src/server'),
-        ...(preset && { preset }),
+        ...(!isStaticPreset(preset) && preset && { preset }),
         ignore: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'],
+        ...(isStaticPreset(preset) && { prerender: { routes: [] } }),
       }),
       mdx({
         default: defineFumadocsConfig({
@@ -104,6 +106,7 @@ export async function createViteConfig(
               [remarkResolveImages, { optimize: !isStaticPreset(preset) }],
               remarkMdxMermaid,
               remarkReadingTime,
+              remarkValidateMdx,
             ],
           },
         }),
@@ -146,8 +149,14 @@ export async function createViteConfig(
     environments: {
       client: {
         build: {
+          manifest: isStaticPreset(preset),
           rollupOptions: {
-            input: path.resolve(packageRoot, 'src/server/entry-client.tsx')
+            input: path.resolve(
+              packageRoot,
+              isStaticPreset(preset)
+                ? 'src/server/entry-static.tsx'
+                : 'src/server/entry-client.tsx',
+            )
           }
         }
       }
@@ -166,12 +175,16 @@ export async function createViteConfig(
           base: path.resolve(projectRoot, '.cache/images'),
         },
       },
-      experimental: {
-        database: true,
-      },
-      database: {
-        default: getDatabaseConnector(preset),
-      },
+      ...(isStaticPreset(preset)
+        ? {}
+        : {
+            experimental: {
+              database: true,
+            },
+            database: {
+              default: getDatabaseConnector(preset),
+            },
+          }),
     },
   };
 }

package/src/themes/default/Page.module.css

@@ -126,6 +126,8 @@
   table-layout: fixed;
   width: 100%;
   margin-bottom: var(--rs-space-5);
+  /* block inherited justify (e.g. from <p align="justify"> in content) without overriding GFM column alignment */
+  text-align: start;
 }
 
 .content table td,

package/src/themes/paper/Layout.module.css

@@ -84,7 +84,3 @@
 .contentFull {
   margin-left: 0;
 }
-
-.hiddenTrigger {
-  display: none;
-}

package/src/themes/paper/Layout.tsx

@@ -6,7 +6,6 @@ import { useLocation, useNavigate } from 'react-router';
 import { getLandingEntries } from '@/lib/config';
 import { getActiveContentDir } from '@/lib/navigation';
 import { usePageContext } from '@/lib/page-context';
-import { Search } from '@/components/ui/search';
 import type { ThemeLayoutProps } from '@/types';
 import { ChapterNav } from './ChapterNav';
 import styles from './Layout.module.css';
@@ -83,7 +82,6 @@ function LayoutInner({
           </aside>
         ) : null}
         <div className={cx(styles.content, classNames?.content, { [styles.contentFull]: !showSidebar })}>
-          {config.search?.enabled && <Search classNames={{ trigger: styles.hiddenTrigger }} />}
           {children}
         </div>
       </Flex>

package/src/themes/paper/Page.module.css

@@ -204,6 +204,8 @@
   table-layout: fixed;
   width: 100%;
   margin-bottom: var(--rs-space-5);
+  /* block inherited justify (e.g. from <p align="justify"> in content) without overriding GFM column alignment */
+  text-align: start;
 }
 
 .content table td,