@raystack/chronicle 0.12.1 → 0.12.3

package/dist/cli/index.js

@@ -496,6 +496,7 @@ async function createViteConfig(options) {
     define: {
       __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentMirror),
       __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
+      __CHRONICLE_PACKAGE_ROOT__: JSON.stringify(packageRoot),
       __CHRONICLE_CONFIG_RAW__: JSON.stringify(rawConfig)
     },
     css: {
@@ -907,6 +908,9 @@ var devCommand = new Command2("dev").description("Start development server").opt
   const { config: config2, projectRoot, configPath } = await loadCLIConfig(options.config);
   const port = parseInt(options.port, 10);
   await linkContent(projectRoot, config2);
+  if (process.platform === "win32" && !process.env.NITRO_DEV_RUNNER) {
+    process.env.NITRO_DEV_RUNNER = "node-process";
+  }
   console.log(chalk3.cyan("Starting dev server..."));
   const { createServer } = await import("vite");
   const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_vite_config(), exports_vite_config));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,8 +43,10 @@
     "@codemirror/view": "^6.39.14",
     "@heroicons/react": "^2.2.0",
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.218.0",
     "@opentelemetry/exporter-prometheus": "^0.214.0",
     "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-logs": "^0.218.0",
     "@opentelemetry/sdk-metrics": "^2.6.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@radix-ui/react-icons": "^1.3.2",

package/src/cli/commands/dev.ts

@@ -16,6 +16,11 @@ export const devCommand = new Command('dev')
 
     await linkContent(projectRoot, config);
 
+    // Nitro 3's default node-worker runner fails on Windows due to Vite 8 environment API incompatibility
+    if (process.platform === 'win32' && !process.env.NITRO_DEV_RUNNER) {
+      process.env.NITRO_DEV_RUNNER = 'node-process';
+    }
+
     console.log(chalk.cyan('Starting dev server...'));
 
     const { createServer } = await import('vite');

package/src/components/api/ApiSkeleton.module.css

@@ -0,0 +1,74 @@
+.layout {
+  padding-left: var(--rs-space-9);
+  padding-right: var(--rs-space-9);
+  width: 100%;
+}
+
+.left {
+  min-width: 0;
+  flex: 0 1 545px;
+}
+
+.right {
+  min-width: 376px;
+  max-width: 500px;
+  width: 100%;
+}
+
+.methodBar {
+  padding: var(--rs-space-3) 0;
+}
+
+.fieldRow {
+  padding: var(--rs-space-3) 0;
+}
+
+.codeBlock {
+  background: var(--rs-color-background-neutral-secondary);
+  border-radius: var(--rs-radius-4);
+  padding: var(--rs-space-5);
+  min-height: 180px;
+}
+
+.responseBlock {
+  background: var(--rs-color-background-neutral-secondary);
+  border-radius: var(--rs-radius-4);
+  padding: var(--rs-space-5);
+  min-height: 120px;
+}
+
+.sidebarGroup {
+  margin-top: var(--rs-space-8);
+  width: 100%;
+  padding: 0 var(--rs-space-3);
+}
+
+.sidebarGroup:first-child {
+  margin-top: 0;
+}
+
+.sidebarItem {
+  padding: var(--rs-space-3) 0;
+}
+
+@media (max-width: 1100px) {
+  .layout {
+    flex-direction: column;
+    gap: var(--rs-space-9);
+  }
+
+  .left,
+  .right {
+    min-width: 0;
+    max-width: 100%;
+    width: 100%;
+  }
+}
+
+@media (max-width: 768px) {
+  .layout {
+    gap: var(--rs-space-5);
+    padding-left: var(--rs-space-5);
+    padding-right: var(--rs-space-5);
+  }
+}

package/src/components/api/ApiSkeleton.tsx

@@ -0,0 +1,105 @@
+import { Skeleton, Flex, Sidebar } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import styles from './ApiSkeleton.module.css';
+import layoutStyles from '@/themes/default/Layout.module.css';
+import apiLayoutStyles from '@/pages/ApiLayout.module.css';
+
+export function ApiPageSkeleton() {
+  return (
+    <Flex align="start" justify="between" className={styles.layout}>
+      <Flex direction="column" gap={9} className={styles.left}>
+        <Flex direction="column" gap={7}>
+          <Flex direction="column" gap={4}>
+            <Skeleton width="40%" height="var(--rs-line-height-t3)" />
+            <Skeleton width="60%" height="var(--rs-line-height-regular)" />
+          </Flex>
+          <Flex align="center" gap={3} className={styles.methodBar}>
+            <Skeleton width="48px" height="24px" />
+            <Skeleton width="200px" height="var(--rs-line-height-regular)" />
+          </Flex>
+        </Flex>
+
+        {[0, 1, 2].map(section => (
+          <Flex direction="column" gap={4} key={section}>
+            <Skeleton width="120px" height="var(--rs-line-height-small)" />
+            {[0, 1, 2, 3].map(row => (
+              <Flex align="center" gap={4} className={styles.fieldRow} key={row}>
+                <Skeleton width="80px" height="var(--rs-line-height-small)" />
+                <Skeleton width="60px" height="var(--rs-line-height-small)" />
+              </Flex>
+            ))}
+          </Flex>
+        ))}
+      </Flex>
+
+      <Flex direction="column" gap={8} className={styles.right}>
+        <Flex direction="column" gap={3} className={styles.codeBlock}>
+          <Skeleton width="50%" height="var(--rs-line-height-small)" />
+          {[0, 1, 2, 3, 4].map(i => (
+            <Skeleton key={i} width={`${70 + (i % 3) * 10}%`} height="var(--rs-line-height-small)" />
+          ))}
+        </Flex>
+        <Flex direction="column" gap={3} className={styles.responseBlock}>
+          <Skeleton width="40%" height="var(--rs-line-height-small)" />
+          {[0, 1, 2].map(i => (
+            <Skeleton key={i} width={`${60 + (i % 2) * 20}%`} height="var(--rs-line-height-small)" />
+          ))}
+        </Flex>
+      </Flex>
+    </Flex>
+  );
+}
+
+function SidebarSkeleton() {
+  return (
+    <>
+      {[0, 1, 2].map(group => (
+        <Flex direction="column" gap={3} className={styles.sidebarGroup} key={group}>
+          <Skeleton width="80px" height="var(--rs-line-height-small)" />
+          {[0, 1, 2, 3].map(item => (
+            <Flex align="center" gap={3} className={styles.sidebarItem} key={item}>
+              <Skeleton width="100%" height="var(--rs-line-height-small)" />
+            </Flex>
+          ))}
+        </Flex>
+      ))}
+    </>
+  );
+}
+
+export function ApiFullSkeleton() {
+  return (
+    <Flex direction="column" className={cx(layoutStyles.layout, apiLayoutStyles.layout)}>
+      <Flex className={layoutStyles.body}>
+        <Sidebar
+          defaultOpen
+          collapsible={false}
+          className={cx(layoutStyles.sidebar, apiLayoutStyles.sidebar)}
+        >
+          <Sidebar.Header className={layoutStyles.sidebarHeader}>
+            <Skeleton width="100px" height="28px" />
+          </Sidebar.Header>
+          <Sidebar.Main className={layoutStyles.sidebarMain}>
+            <SidebarSkeleton />
+          </Sidebar.Main>
+        </Sidebar>
+        <Flex direction="column" className={layoutStyles.mainArea}>
+          <div className={layoutStyles.cardWrapper}>
+            <div className={layoutStyles.card}>
+              <nav className={layoutStyles.subNav}>
+                <Flex align="center" gap={3}>
+                  <Skeleton width="24px" height="24px" />
+                  <Skeleton width="24px" height="24px" />
+                  <Skeleton width="150px" height="var(--rs-line-height-small)" />
+                </Flex>
+              </nav>
+              <main className={cx(layoutStyles.content, apiLayoutStyles.content)}>
+                <ApiPageSkeleton />
+              </main>
+            </div>
+          </div>
+        </Flex>
+      </Flex>
+    </Flex>
+  );
+}

package/src/components/api/index.ts

@@ -5,3 +5,4 @@ export { ApiResponsePanel } from './api-response-panel'
 export { PlaygroundDialog } from './playground-dialog'
 export { MethodBadge } from './method-badge'
 export { JsonEditor } from './json-editor'
+export { ApiPageSkeleton, ApiFullSkeleton } from './ApiSkeleton'

package/src/lib/api-routes.ts

@@ -84,7 +84,7 @@ export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatc
   return null
 }
 
-export function buildApiPageTree(specs: ApiSpec[]): Root {
+export function buildApiPageTree(specs: ApiSpec[] = []): Root {
   const children: Node[] = []
 
   for (const spec of specs) {

package/src/lib/tree-utils.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from 'bun:test'
-import type { Node } from 'fumadocs-core/page-tree'
-import { getFirstPageUrl, findFolderFirstPage, resolveDocsRedirect } from './tree-utils'
+import type { Node, Root } from 'fumadocs-core/page-tree'
+import type { ChronicleConfig } from '@/types'
+import type { VersionContext } from './version-source'
+import { getFirstPageUrl, findFolderFirstPage, resolveDocsRedirect, resolvePageAndSlug, compactTree } from './tree-utils'
 
 function page(url: string, name = 'Page'): Node {
   return { type: 'page', name, url } as Node
@@ -111,3 +113,191 @@ describe('resolveDocsRedirect', () => {
       .toBe('/docs/custom')
   })
 })
+
+describe('resolvePageAndSlug', () => {
+  const treeDef = {
+    children: [
+      page('/docs/intro'),
+      folder('Guides', [page('/docs/guides/install'), page('/docs/guides/config')]),
+    ] as Node[],
+  }
+
+  const config: ChronicleConfig = {
+    site: { title: 'Test' },
+    content: [{ dir: 'docs', label: 'Docs' }],
+  }
+
+  const version: VersionContext = { dir: null, urlPrefix: '' }
+
+  function makeDeps(pages: Record<string, unknown> = {}) {
+    return {
+      getPage: async (slug: string[]) => pages[slug.join('/')] ?? null,
+      getPageTree: async () => treeDef,
+      isDraft: () => false,
+      config,
+      version,
+    }
+  }
+
+  test('returns page when found directly', async () => {
+    const pageObj = { title: 'Intro' }
+    const result = await resolvePageAndSlug(['docs', 'intro'], makeDeps({ 'docs/intro': pageObj }))
+    expect(result).toEqual({ page: pageObj, slug: ['docs', 'intro'] })
+  })
+
+  test('resolves folder slug to first child page', async () => {
+    const installPage = { title: 'Install' }
+    const deps = makeDeps({ 'docs/guides/install': installPage })
+    const result = await resolvePageAndSlug(['docs', 'guides'], deps)
+    expect(result).toEqual({ page: installPage, slug: ['docs', 'guides', 'install'] })
+  })
+
+  test('returns null for non-matching slug', async () => {
+    const result = await resolvePageAndSlug(['docs', 'nonexistent'], makeDeps())
+    expect(result).toBeNull()
+  })
+
+  test('returns null when resolved page is draft', async () => {
+    const draftPage = { title: 'Draft' }
+    const deps = {
+      ...makeDeps({ 'docs/guides/install': draftPage }),
+      isDraft: () => true,
+    }
+    const result = await resolvePageAndSlug(['docs', 'guides'], deps)
+    expect(result).toBeNull()
+  })
+})
+
+describe('compactTree', () => {
+  test('strips $ref and $id from page nodes', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'page', name: 'Intro', url: '/docs/intro',
+        $ref: 'docs/intro.mdx', $id: 'docs/intro.mdx',
+      } as Node],
+    }
+    const result = compactTree(tree)
+    expect(result.children[0]).toEqual({ type: 'page', name: 'Intro', url: '/docs/intro' })
+  })
+
+  test('strips description and root from folder nodes', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'folder', name: 'Guides',
+        description: 'Guide section', root: true,
+        children: [{ type: 'page', name: 'Install', url: '/guides/install', $ref: 'install.mdx' } as Node],
+      } as Node],
+    }
+    const result = compactTree(tree)
+    const folder = result.children[0] as any
+    expect(folder.description).toBeUndefined()
+    expect(folder.root).toBeUndefined()
+    expect(folder.name).toBe('Guides')
+    expect(folder.children[0]).toEqual({ type: 'page', name: 'Install', url: '/guides/install' })
+  })
+
+  test('preserves separator nodes', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{ type: 'separator' } as Node],
+    }
+    const result = compactTree(tree)
+    expect(result.children[0]).toEqual({ type: 'separator' })
+  })
+
+  test('preserves separator name and icon', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{ type: 'separator', name: 'Section', icon: 'star' } as Node],
+    }
+    const result = compactTree(tree)
+    expect(result.children[0]).toEqual({ type: 'separator', name: 'Section', icon: 'star' })
+  })
+
+  test('preserves folder index and strips its extra fields', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'folder', name: 'Docs',
+        index: { type: 'page', name: 'Overview', url: '/docs', $ref: 'docs/index.mdx' },
+        children: [{ type: 'page', name: 'Intro', url: '/docs/intro' } as Node],
+      } as Node],
+    }
+    const result = compactTree(tree)
+    const folder = result.children[0] as any
+    expect(folder.index).toEqual({ type: 'page', name: 'Overview', url: '/docs' })
+  })
+
+  test('preserves icon field', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{ type: 'page', name: 'Home', url: '/', icon: 'home', $id: 'x' } as Node],
+    }
+    const result = compactTree(tree)
+    expect(result.children[0]).toEqual({ type: 'page', name: 'Home', url: '/', icon: 'home' })
+  })
+
+  test('page leaf only keeps type, name, url, icon', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'page', name: 'Test', url: '/test', icon: 'doc',
+        $ref: 'test.mdx', $id: 'test', description: 'A test page', external: true,
+      } as Node],
+    }
+    const result = compactTree(tree)
+    const node = result.children[0] as any
+    expect(Object.keys(node).sort()).toEqual(['icon', 'name', 'type', 'url'])
+  })
+
+  test('separator leaf strips unknown fields', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{ type: 'separator', name: 'Divider', $id: 'sep1', root: true } as Node],
+    }
+    const result = compactTree(tree)
+    const node = result.children[0] as any
+    expect(Object.keys(node).sort()).toEqual(['name', 'type'])
+  })
+
+  test('folder index is compacted as leaf', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'folder', name: 'Docs',
+        index: { type: 'page', name: 'Index', url: '/docs', $ref: 'index.mdx', $id: 'idx', description: 'main' },
+        children: [],
+      } as Node],
+    }
+    const result = compactTree(tree)
+    const idx = (result.children[0] as any).index
+    expect(Object.keys(idx).sort()).toEqual(['name', 'type', 'url'])
+  })
+
+  test('recursively compacts nested folders', () => {
+    const tree: Root = {
+      name: 'root',
+      children: [{
+        type: 'folder', name: 'L1', $ref: 'l1',
+        children: [{
+          type: 'folder', name: 'L2', $ref: 'l2',
+          children: [{ type: 'page', name: 'Deep', url: '/l1/l2/deep', $ref: 'deep.mdx', $id: 'deep' } as Node],
+        } as Node],
+      } as Node],
+    }
+    const result = compactTree(tree)
+    const l1 = result.children[0] as any
+    const l2 = l1.children[0] as any
+    const deep = l2.children[0]
+    expect(l1.$ref).toBeUndefined()
+    expect(l2.$ref).toBeUndefined()
+    expect(deep).toEqual({ type: 'page', name: 'Deep', url: '/l1/l2/deep' })
+  })
+
+  test('preserves tree name', () => {
+    const tree: Root = { name: 'custom', children: [] }
+    expect(compactTree(tree).name).toBe('custom')
+  })
+})

package/src/lib/tree-utils.ts

@@ -1,4 +1,32 @@
-import type { Node } from 'fumadocs-core/page-tree';
+import type { Folder, Node, Root } from 'fumadocs-core/page-tree';
+import type { ChronicleConfig } from '@/types';
+import type { VersionContext } from './version-source';
+
+const KEEP_FIELDS = new Set(['type', 'name', 'url', 'icon', 'children', 'index']);
+
+function compactLeaf(node: Node): Node {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (KEEP_FIELDS.has(k)) out[k] = v;
+  }
+  return out as Node;
+}
+
+function compactNode(node: Node): Node {
+  if (node.type !== 'folder') return compactLeaf(node);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (!KEEP_FIELDS.has(k)) continue;
+    if (k === 'children') out.children = (v as Node[]).map(compactNode);
+    else if (k === 'index') out.index = compactLeaf(v as Node);
+    else out[k] = v;
+  }
+  return out as Node;
+}
+
+export function compactTree(tree: Root): Root {
+  return { ...tree, children: tree.children.map(compactNode) };
+}
 
 export const NodeType = {
   Page: 'page',
@@ -55,3 +83,37 @@ export function resolveDocsRedirect(
 
   return findFolderFirstPage(tree.children, `/${slug.join('/')}`);
 }
+
+interface ResolvePageDeps {
+  getPage: (slug: string[]) => Promise<unknown>;
+  getPageTree: () => Promise<{ children: Node[] }>;
+  isDraft: (page: unknown) => boolean;
+  config: ChronicleConfig;
+  version: VersionContext;
+}
+
+export async function resolvePageAndSlug(slug: string[], deps: ResolvePageDeps) {
+  const { getPage, getPageTree, isDraft, config, version } = deps;
+
+  const page = await getPage(slug);
+  if (page && !isDraft(page)) return { page, slug };
+
+  const slugWithoutVersion = version.dir && slug[0] === version.dir
+    ? slug.slice(1)
+    : slug;
+
+  const tree = await getPageTree();
+  const contentEntries = version.dir
+    ? config.versions?.find(v => v.dir === version.dir)?.content ?? config.content
+    : config.content;
+  const contentConfig = contentEntries?.find(c => c.dir === slugWithoutVersion[0]);
+  const redirectUrl = resolveDocsRedirect(slugWithoutVersion, tree, contentConfig);
+  if (!redirectUrl) return null;
+
+  const fullUrl = version.urlPrefix ? `${version.urlPrefix}${redirectUrl}` : redirectUrl;
+  const resolvedSlug = fullUrl.split('/').filter(Boolean);
+  const resolvedPage = await getPage(resolvedSlug);
+  if (!resolvedPage || isDraft(resolvedPage)) return null;
+
+  return { page: resolvedPage, slug: resolvedSlug };
+}

package/src/pages/ApiLayout.tsx

@@ -1,5 +1,6 @@
 import { cx } from 'class-variance-authority';
 import type { ReactNode } from 'react';
+import { ApiFullSkeleton } from '@/components/api/ApiSkeleton';
 import { buildApiPageTree } from '@/lib/api-routes';
 import { usePageContext } from '@/lib/page-context';
 import { getTheme } from '@/themes/registry';
@@ -10,7 +11,10 @@ interface ApiLayoutProps {
 }
 
 export function ApiLayout({ children }: ApiLayoutProps) {
-  const { config, apiSpecs } = usePageContext();
+  const { config, apiSpecs, isLoading } = usePageContext();
+
+  if (isLoading) return <ApiFullSkeleton />;
+
   const { Layout, className } = getTheme(config.theme?.name);
   const tree = buildApiPageTree(apiSpecs);
 

package/src/pages/ApiPage.tsx

@@ -1,6 +1,7 @@
 import type { OpenAPIV3 } from 'openapi-types';
 import { Navigate } from 'react-router';
 import { ApiOverview } from '@/components/api';
+import { ApiPageSkeleton } from '@/components/api/ApiSkeleton';
 import { findApiOperation, getFirstApiUrl } from '@/lib/api-routes';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
@@ -10,7 +11,9 @@ interface ApiPageProps {
 }
 
 export function ApiPage({ slug }: ApiPageProps) {
-  const { config, apiSpecs } = usePageContext();
+  const { config, apiSpecs, isLoading } = usePageContext();
+
+  if (isLoading) return <ApiPageSkeleton />;
 
   if (slug.length === 0) {
     const firstUrl = getFirstApiUrl(apiSpecs);

package/src/pages/DocsPage.tsx

@@ -38,7 +38,8 @@ export function DocsPage({ slug }: DocsPageProps) {
           '@type': 'Article',
           headline: page.frontmatter.title,
           description: page.frontmatter.description,
-          ...(pageUrl && { url: pageUrl })
+          ...(pageUrl && { url: pageUrl }),
+          ...(page.frontmatter.lastModified && { dateModified: new Date(page.frontmatter.lastModified).toISOString() }),
         }}
       />
       <Page

package/src/pages/LandingPage.tsx

@@ -1,6 +1,7 @@
 import { FolderIcon } from '@heroicons/react/24/outline';
 import { Link as RouterLink } from 'react-router';
 import { getLandingEntries } from '@/lib/config';
+import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import styles from './LandingPage.module.css';
 
@@ -13,6 +14,12 @@ export function LandingPage() {
     : `${config.site.title} — ${versionLabel(config, version.dir)}`;
 
   return (
+    <>
+      <Head
+        title={version.dir ? `${config.site.title} — ${versionLabel(config, version.dir)}` : 'Documentation'}
+        description={config.site.description}
+        config={config}
+      />
     <div className={styles.root}>
       <div className={styles.header}>
         <h1 className={styles.title}>{heading}</h1>
@@ -42,6 +49,7 @@ export function LandingPage() {
         ))}
       </div>
     </div>
+    </>
   );
 }
 

package/src/server/App.tsx

@@ -4,7 +4,6 @@ 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 { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import type { ChronicleConfig } from '@/types';
@@ -69,22 +68,25 @@ function PageFallback() {
 }
 
 function RootHead({ config }: { config: ChronicleConfig }) {
-  return (
-    <Head
-      title={config.site.title}
-      description={config.site.description}
-      config={config}
-      jsonLd={
-        config.url
-          ? {
-              '@context': 'https://schema.org',
-              '@type': 'WebSite',
-              name: config.site.title,
-              description: config.site.description,
-              url: config.url
-            }
-          : undefined
+  const siteJsonLd = config.url
+    ? {
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        name: config.site.title,
+        description: config.site.description,
+        url: config.url,
       }
-    />
+    : null;
+
+  return (
+    <>
+      <title>{config.site.title}</title>
+      {siteJsonLd && (
+        <script
+          type='application/ld+json'
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(siteJsonLd, null, 2) }}
+        />
+      )}
+    </>
   );
 }

package/src/server/api/page.ts

@@ -1,19 +1,25 @@
 import { defineHandler, HTTPError } from 'nitro';
-import { getPage, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath, getPageImages, isDraft } from '@/lib/source';
+import { loadConfig } from '@/lib/config';
+import { getPage, getPageTree, isDraft, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath, getPageImages } from '@/lib/source';
+import { resolvePageAndSlug } from '@/lib/tree-utils';
+import { resolveVersionFromUrl } from '@/lib/version-source';
 
 export default defineHandler(async event => {
   const slugParam = event.url.searchParams.get('slug') ?? '';
   const slug = slugParam ? slugParam.split(',').filter(Boolean) : [];
-  const page = await getPage(slug);
+  const config = loadConfig();
+  const version = resolveVersionFromUrl(`/${slug.join('/')}`, config);
+  const resolved = await resolvePageAndSlug(slug, { getPage, getPageTree, isDraft, config, version });
 
-  if (!page || isDraft(page)) {
+  if (!resolved) {
     throw new HTTPError({ status: 404, message: 'Page not found' });
   }
 
-  const nav = await getPageNav(slug);
+  const { page, slug: resolvedSlug } = resolved;
+  const nav = await getPageNav(resolvedSlug);
 
   return Response.json({
-    frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+    frontmatter: extractFrontmatter(page, resolvedSlug[resolvedSlug.length - 1]),
     relativePath: getRelativePath(page),
     originalPath: getOriginalPath(page),
     images: getPageImages(page),

package/src/server/entry-server.tsx

@@ -9,10 +9,13 @@ import { getApiConfigsForVersion, loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
-import { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath, getPageImages, isDraft } from '@/lib/source';
+import { getPage, getPageTree, isDraft, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath, getPageImages } from '@/lib/source';
 import { getFirstApiUrl } from '@/lib/api-routes';
 import { StatusCodes } from 'http-status-codes';
-import { resolveDocsRedirect } from '@/lib/tree-utils';
+import { resolvePageAndSlug, resolveDocsRedirect, compactTree } from '@/lib/tree-utils';
+import { filterPageTreeByVersion, filterPageTreeByContentDir } from '@/lib/version-source';
+import { getActiveContentDir } from '@/lib/navigation';
+import { getLatestContentRoots, getVersionContentRoots } from '@/lib/config';
 import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
 import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
 import { useNitroApp } from 'nitro/app';
@@ -21,10 +24,31 @@ import { App } from './App';
 import clientAssets from './entry-client?assets=client';
 import serverAssets from './entry-server?assets=ssr';
 
+function errorResponse(status: number, title: string, message: string): Response {
+  const safe = message.replace(/[<>&"]/g, '');
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${status} — ${title}</title>
+</head>
+<body>
+  <h1>${status} — ${title}</h1>
+  <p>${safe}</p>
+</body>
+</html>`;
+  return new Response(html, {
+    status,
+    headers: { 'Content-Type': 'text/html;charset=utf-8' },
+  });
+}
+
 export default {
   async fetch(req: Request) {
     const url = new URL(req.url);
     const pathname = decodeURIComponent(url.pathname);
+    try {
 
     const config = loadConfig();
     const route = resolveRoute(pathname, config);
@@ -46,11 +70,16 @@ export default {
       : [];
     const apiSpecs = apiConfigs.length ? await loadApiSpecs(apiConfigs) : [];
 
-    const [tree, rawPage] = await Promise.all([
-      getPageTree(),
-      route.type === RouteType.DocsPage ? getPage(route.slug) : Promise.resolve(null),
-    ]);
-    const page = rawPage && isDraft(rawPage) ? null : rawPage;
+    const fullTree = await getPageTree();
+    const versionTree = filterPageTreeByVersion(fullTree, route.version, config);
+    const contentDirs = route.version.dir
+      ? getVersionContentRoots(config, route.version.dir)
+      : getLatestContentRoots(config);
+    const activeDir = getActiveContentDir(pathname, config);
+    const scopedTree = contentDirs.length === 1 && activeDir
+      ? filterPageTreeByContentDir(versionTree, route.version, activeDir)
+      : versionTree;
+    const tree = compactTree(scopedTree);
 
     // SSR redirects for index pages
     if (route.type === RouteType.ApiIndex) {
@@ -60,23 +89,20 @@ export default {
       }
     }
 
-    if (route.type === RouteType.DocsPage && !page) {
-      const versionPrefix = route.version.urlPrefix;
-      const slugWithoutVersion = versionPrefix && route.slug[0] === route.version.dir
-        ? route.slug.slice(1)
-        : route.slug;
-      const contentEntries = route.version.dir
-        ? config.versions?.find(v => v.dir === route.version.dir)?.content ?? config.content
-        : config.content;
-      const contentConfig = contentEntries?.find((c: { dir: string }) => c.dir === slugWithoutVersion[0]);
-      const redirectUrl = resolveDocsRedirect(slugWithoutVersion, tree, contentConfig);
-      if (redirectUrl) {
-        const fullUrl = versionPrefix ? `${versionPrefix}${redirectUrl}` : redirectUrl;
-        return new Response(null, { status: StatusCodes.TEMPORARY_REDIRECT, headers: { Location: fullUrl } });
-      }
+    const resolved = route.type === RouteType.DocsPage
+      ? await resolvePageAndSlug(route.slug, { getPage, getPageTree, isDraft, config, version: route.version })
+      : null;
+    const page = resolved?.page ?? null;
+    const resolvedSlug = resolved?.slug ?? pageSlug;
+
+    if (route.type === RouteType.DocsPage && resolved && resolved.slug.join('/') !== route.slug.join('/')) {
+      return new Response(null, {
+        status: StatusCodes.TEMPORARY_REDIRECT,
+        headers: { Location: `/${resolved.slug.join('/')}` },
+      });
     }
 
-    const nav = page ? await getPageNav(pageSlug) : { prev: null, next: null };
+    const nav = page ? await getPageNav(resolvedSlug) : { prev: null, next: null };
 
     const relativePath = page ? getRelativePath(page) : null;
     const originalPath = page ? getOriginalPath(page) : null;
@@ -85,9 +111,9 @@ export default {
 
     const pageData = page
       ? {
-          slug: pageSlug,
+          slug: resolvedSlug,
           frontmatter: {
-            ...extractFrontmatter(page, pageSlug[pageSlug.length - 1]),
+            ...extractFrontmatter(page, resolvedSlug[resolvedSlug.length - 1]),
             _readingTime: mdxModule?._readingTime,
           },
           content: mdxModule?.default
@@ -102,7 +128,7 @@ export default {
     const embeddedData = {
       config,
       tree,
-      slug: pageSlug,
+      slug: resolvedSlug,
       version: route.version,
       frontmatter: pageData?.frontmatter ?? null,
       relativePath,
@@ -132,6 +158,16 @@ export default {
             const href = isLocalImage(src) && !isSvg(src) ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
             return <link key={src} rel="preload" as="image" href={href} />;
           })}
+          {isApiRoute && (
+            <link
+              rel="preload"
+              as="fetch"
+              crossOrigin="anonymous"
+              href={route.version.dir
+                ? `/api/specs?version=${encodeURIComponent(route.version.dir)}`
+                : '/api/specs'}
+            />
+          )}
           <script type="module" src={assets.entry} />
           <script dangerouslySetInnerHTML={{ __html: `window.__PAGE_DATA__ = ${safeJson}` }} />
         </head>
@@ -169,5 +205,9 @@ export default {
       status,
       headers: { 'Content-Type': 'text/html;charset=utf-8' },
     });
+    } catch (err) {
+      console.error(`[chronicle] SSR error for ${pathname}:`, err);
+      return errorResponse(500, 'Internal Server Error', err instanceof Error ? err.message : String(err));
+    }
   },
 };

package/src/server/plugins/telemetry.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test'
+import { toEndpoint } from './telemetry'
+
+describe('toEndpoint', () => {
+  test('root path', () => {
+    expect(toEndpoint('/')).toBe('/')
+  })
+
+  test('docs pages map to /docs/:slug', () => {
+    expect(toEndpoint('/docs/intro')).toBe('/docs/:slug')
+    expect(toEndpoint('/docs/guides/installation')).toBe('/docs/:slug')
+    expect(toEndpoint('/developer/gettingstarted/auth')).toBe('/docs/:slug')
+  })
+
+  test('api internal routes keep exact path', () => {
+    expect(toEndpoint('/api/page')).toBe('/api/page')
+    expect(toEndpoint('/api/search')).toBe('/api/search')
+    expect(toEndpoint('/api/specs')).toBe('/api/specs')
+    expect(toEndpoint('/api/health')).toBe('/api/health')
+  })
+
+  test('api reference pages map to /apis/:slug', () => {
+    expect(toEndpoint('/apis/petstore/listPets')).toBe('/apis/:slug')
+    expect(toEndpoint('/apis/frontier/getUser')).toBe('/apis/:slug')
+  })
+
+  test('assets map to /assets/:file', () => {
+    expect(toEndpoint('/assets/chunk-abc123.js')).toBe('/assets/:file')
+    expect(toEndpoint('/assets/style-xyz.css')).toBe('/assets/:file')
+  })
+
+  test('content paths map to /_content/:path', () => {
+    expect(toEndpoint('/_content/docs/intro.mdx')).toBe('/_content/:path')
+  })
+
+  test('static routes keep exact path', () => {
+    expect(toEndpoint('/llms.txt')).toBe('/llms.txt')
+    expect(toEndpoint('/robots.txt')).toBe('/robots.txt')
+    expect(toEndpoint('/sitemap.xml')).toBe('/sitemap.xml')
+    expect(toEndpoint('/og')).toBe('/og')
+  })
+
+  test('versioned docs map to /docs/:slug', () => {
+    expect(toEndpoint('/v1/docs/intro')).toBe('/docs/:slug')
+    expect(toEndpoint('/v2/guides/setup')).toBe('/docs/:slug')
+  })
+})

package/src/server/plugins/telemetry.ts

@@ -1,6 +1,12 @@
 import type { Counter, Histogram } from '@opentelemetry/api'
 import { MeterProvider } from '@opentelemetry/sdk-metrics'
 import { PrometheusExporter } from '@opentelemetry/exporter-prometheus'
+import {
+  LoggerProvider,
+  SimpleLogRecordProcessor,
+  ConsoleLogRecordExporter,
+} from '@opentelemetry/sdk-logs'
+import { SeverityNumber } from '@opentelemetry/api-logs'
 import { resourceFromAttributes } from '@opentelemetry/resources'
 import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
 import type { H3Event } from 'h3'
@@ -13,6 +19,33 @@ declare module 'nitro/types' {
   }
 }
 
+const ROUTES = {
+  ROOT: '/',
+  DOCS: '/docs/:slug',
+  API_INTERNAL: '/api/:action',
+  API_REFERENCE: '/apis/:slug',
+  ASSETS: '/assets/:file',
+  CONTENT: '/_content/:path',
+} as const
+
+const ENDPOINT_MAP: [string, string | null][] = [
+  ['/api/', null],
+  ['/_content/', ROUTES.CONTENT],
+  ['/apis/', ROUTES.API_REFERENCE],
+  ['/assets/', ROUTES.ASSETS],
+]
+
+const STATIC_ROUTES = new Set(['/llms.txt', '/robots.txt', '/sitemap.xml', '/og'])
+
+export function toEndpoint(pathname: string): string {
+  if (pathname === '/') return ROUTES.ROOT;
+  for (const [prefix, template] of ENDPOINT_MAP) {
+    if (pathname.startsWith(prefix)) return template ?? pathname;
+  }
+  if (STATIC_ROUTES.has(pathname)) return pathname;
+  return ROUTES.DOCS;
+}
+
 export default definePlugin((nitroApp) => {
   const config = loadConfig()
   if (!config.telemetry?.enabled) return
@@ -26,6 +59,12 @@ export default definePlugin((nitroApp) => {
   const provider = new MeterProvider({ resource, readers: [exporter] })
   const meter = provider.getMeter('chronicle')
 
+  const loggerProvider = new LoggerProvider({
+    resource,
+    processors: [new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())],
+  })
+  const logger = loggerProvider.getLogger('chronicle')
+
   const requestCounter: Counter = meter.createCounter('http_server_request_total', {
     description: 'Total HTTP requests',
   })
@@ -37,12 +76,13 @@ export default definePlugin((nitroApp) => {
   })
 
   nitroApp.hooks.hook('close', async () => {
+    await loggerProvider.shutdown()
     await provider.shutdown()
     await exporter.shutdown()
   })
 
   nitroApp.hooks.hook('chronicle:ssr-rendered', (route, status, durationMs) => {
-    ssrRenderDuration.record(durationMs, { route, status })
+    ssrRenderDuration.record(durationMs, { route: toEndpoint(route), status })
   })
 
   nitroApp.hooks.hook('request', (event) => {
@@ -55,7 +95,29 @@ export default definePlugin((nitroApp) => {
     const duration = performance.now() - start
     const method = event.req.method
     const route = new URL(event.req.url).pathname
-    requestCounter.add(1, { method, route, status: res.status })
-    requestDuration.record(duration, { method, route, status: res.status })
+    const endpoint = toEndpoint(route)
+
+    const clientIp =
+      event.req.headers['x-forwarded-for']?.toString().split(',')[0].trim() ??
+      event.req.headers['x-real-ip']?.toString() ??
+      event.req.socket?.remoteAddress ??
+      'unknown'
+
+    requestCounter.add(1, { method, endpoint, status: res.status })
+    requestDuration.record(duration, { method, endpoint, status: res.status })
+
+    logger.emit({
+      severityNumber: SeverityNumber.INFO,
+      severityText: 'INFO',
+      body: `${method} ${route} ${res.status} ${duration.toFixed(1)}ms`,
+      attributes: {
+        'client.address': clientIp,
+        'http.request.method': method,
+        'url.path': route,
+        'http.response.status_code': res.status,
+        'http.request.duration_ms': Math.round(duration),
+      },
+    })
+
   })
 })

package/src/server/routes/og-utils.ts

@@ -0,0 +1,32 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MIME_MAP: Record<string, string> = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+};
+
+export function getLogoDataUri(data: Buffer, filePath: string): string | null {
+  const ext = path.extname(filePath).toLowerCase();
+  const mime = MIME_MAP[ext];
+  if (!mime) return null;
+  return `data:${mime};base64,${data.toString('base64')}`;
+}
+
+export async function loadLogo(projectRoot: string, logoPath: string): Promise<string | null> {
+  try {
+    const filePath = path.resolve(projectRoot, 'public', logoPath.replace(/^\//, ''));
+    const data = await fs.readFile(filePath);
+    return getLogoDataUri(data, filePath);
+  } catch {
+    return null;
+  }
+}
+
+export async function loadFont(packageRoot: string): Promise<ArrayBuffer> {
+  const fontPath = path.resolve(packageRoot, 'src/fonts/Inter-Regular.ttf');
+  const buffer = await fs.readFile(fontPath);
+  return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+}

package/src/server/routes/og.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import path from 'node:path';
+import { getLogoDataUri, loadLogo, loadFont } from './og-utils';
+
+const PACKAGE_ROOT = path.resolve(__dirname, '../../..');
+const FIXTURES = path.resolve(__dirname, '__fixtures__');
+
+describe('getLogoDataUri', () => {
+  test('svg file returns svg mime type', () => {
+    const data = Buffer.from('<svg></svg>');
+    const result = getLogoDataUri(data, '/logo.svg');
+    expect(result).toStartWith('data:image/svg+xml;base64,');
+  });
+
+  test('png file returns png mime type', () => {
+    const data = Buffer.from('fake-png');
+    const result = getLogoDataUri(data, '/logo.png');
+    expect(result).toStartWith('data:image/png;base64,');
+  });
+
+  test('jpg file returns jpeg mime type', () => {
+    const data = Buffer.from('fake-jpg');
+    const result = getLogoDataUri(data, '/photo.jpg');
+    expect(result).toStartWith('data:image/jpeg;base64,');
+  });
+
+  test('returns null for unsupported format', () => {
+    const data = Buffer.from('fake-webp');
+    const result = getLogoDataUri(data, '/logo.webp');
+    expect(result).toBeNull();
+  });
+
+  test('encodes data as base64', () => {
+    const content = '<svg xmlns="http://www.w3.org/2000/svg"></svg>';
+    const data = Buffer.from(content);
+    const result = getLogoDataUri(data, '/icon.svg');
+    const base64 = result!.split(',')[1];
+    expect(Buffer.from(base64, 'base64').toString()).toBe(content);
+  });
+});
+
+describe('loadLogo', () => {
+  test('returns null for nonexistent file', async () => {
+    const result = await loadLogo('/nonexistent', '/logo.svg');
+    expect(result).toBeNull();
+  });
+
+  test('strips leading slash from logo path', async () => {
+    const result = await loadLogo('/nonexistent', '/nested/logo.svg');
+    expect(result).toBeNull();
+  });
+});
+
+describe('loadFont', () => {
+  test('loads Inter font from package', async () => {
+    const font = await loadFont(PACKAGE_ROOT);
+    expect(font.byteLength).toBeGreaterThan(0);
+  });
+
+  test('throws for invalid path', async () => {
+    expect(loadFont('/nonexistent')).rejects.toThrow();
+  });
+});

package/src/server/routes/og.tsx

@@ -2,23 +2,10 @@ import { defineHandler } from 'nitro';
 import React from 'react';
 import satori from 'satori';
 import { loadConfig } from '@/lib/config';
+import { loadFont, loadLogo } from './og-utils';
 
 let fontData: ArrayBuffer | null = null;
-
-async function loadFont(): Promise<ArrayBuffer> {
-  if (fontData) return fontData;
-
-  try {
-    const response = await fetch(
-      'https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiA.woff2'
-    );
-    fontData = await response.arrayBuffer();
-  } catch {
-    fontData = new ArrayBuffer(0);
-  }
-
-  return fontData;
-}
+let cachedLogo: string | null | undefined;
 
 export default defineHandler(async event => {
   const config = loadConfig();
@@ -26,7 +13,12 @@ export default defineHandler(async event => {
   const description = event.url.searchParams.get('description') ?? '';
   const siteName = config.site.title;
 
-  const font = await loadFont();
+  if (!fontData) fontData = await loadFont(__CHRONICLE_PACKAGE_ROOT__);
+  if (cachedLogo === undefined) {
+    cachedLogo = config.logo?.dark
+      ? await loadLogo(__CHRONICLE_PROJECT_ROOT__, config.logo.dark)
+      : null;
+  }
 
   const svg = await satori(
     <div
@@ -41,8 +33,18 @@ export default defineHandler(async event => {
         color: '#fafafa',
       }}
     >
-      <div style={{ fontSize: 24, color: '#888', marginBottom: 16 }}>
-        {siteName}
+      <div style={{ display: 'flex', alignItems: 'center', marginBottom: 16 }}>
+        {cachedLogo && (
+          <img
+            src={cachedLogo}
+            width={48}
+            height={48}
+            style={{ marginRight: 16 }}
+          />
+        )}
+        <div style={{ fontSize: 32, color: '#888' }}>
+          {siteName}
+        </div>
       </div>
       <div
         style={{
@@ -64,7 +66,7 @@ export default defineHandler(async event => {
       width: 1200,
       height: 630,
       fonts: [
-        { name: 'Inter', data: font, weight: 400, style: 'normal' as const },
+        { name: 'Inter', data: fontData, weight: 400, style: 'normal' as const },
       ],
     },
   );

package/src/server/vite-config.ts

@@ -131,6 +131,7 @@ export async function createViteConfig(
     define: {
       __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentMirror),
       __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
+      __CHRONICLE_PACKAGE_ROOT__: JSON.stringify(packageRoot),
       __CHRONICLE_CONFIG_RAW__: JSON.stringify(rawConfig),
     },
     css: {

package/src/types/globals.d.ts

@@ -1,4 +1,5 @@
 // Vite build-time constants (injected via define in vite-config.ts)
 declare const __CHRONICLE_CONTENT_DIR__: string
 declare const __CHRONICLE_PROJECT_ROOT__: string
+declare const __CHRONICLE_PACKAGE_ROOT__: string
 declare const __CHRONICLE_CONFIG_RAW__: string | null