@raystack/chronicle 0.12.0 → 0.12.2

package/dist/cli/index.js

@@ -71,6 +71,29 @@ var init_image_utils = () => {};
 // src/lib/remark-resolve-images.ts
 import path4 from "node:path";
 import { visit } from "unist-util-visit";
+function parseImageParams(src) {
+  const qIdx = src.indexOf("?");
+  if (qIdx === -1)
+    return { base: src, params: {} };
+  const base = src.slice(0, qIdx);
+  const search = new URLSearchParams(src.slice(qIdx + 1));
+  const params = {};
+  if (search.has("w"))
+    params.w = Number.parseInt(search.get("w"), 10);
+  if (search.has("q"))
+    params.q = Number.parseInt(search.get("q"), 10);
+  return { base, params };
+}
+function appendParams(url, params) {
+  if (!params.w && !params.q)
+    return url;
+  const qs = new URLSearchParams;
+  if (params.w)
+    qs.set("w", String(params.w));
+  if (params.q)
+    qs.set("q", String(params.q));
+  return `${url}?${qs}`;
+}
 function resolveUrl(src, dir) {
   const normalized = src.replace(/\\/g, "/");
   if (/^[a-z][a-z0-9+\-.]*:/i.test(normalized))
@@ -86,9 +109,12 @@ function resolveUrl(src, dir) {
   return `/_content/${path4.posix.normalize(path4.posix.join(dir, normalized))}`;
 }
 function optimizeUrl(url, optimize) {
-  if (optimize && isLocalImage(url) && !isSvg(url))
-    return buildOptimizedUrl(url, DEFAULT_WIDTH);
-  return url;
+  const { base, params } = parseImageParams(url);
+  const width = params.w || DEFAULT_WIDTH;
+  const quality = params.q;
+  if (optimize && isLocalImage(base) && !isSvg(base))
+    return buildOptimizedUrl(base, width, quality);
+  return base;
 }
 var remarkResolveImages = (options) => {
   const optimize = options?.optimize ?? true;
@@ -112,15 +138,17 @@ var remarkResolveImages = (options) => {
     visit(tree, "image", (node) => {
       if (!node.url)
         return;
-      node.url = resolveUrl(node.url, dir);
-      collect(node.url);
-      node.url = optimizeUrl(node.url, optimize);
+      const { base, params } = parseImageParams(node.url);
+      const resolved = resolveUrl(base, dir);
+      collect(resolved);
+      node.url = optimizeUrl(appendParams(resolved, params), optimize);
     });
     visit(tree, "html", (node) => {
       node.value = node.value.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_, before, src, after) => {
-        const resolved = resolveUrl(src, dir);
+        const { base, params } = parseImageParams(src);
+        const resolved = resolveUrl(base, dir);
         collect(resolved);
-        return `${before}${optimizeUrl(resolved, optimize)}${after}`;
+        return `${before}${optimizeUrl(appendParams(resolved, params), optimize)}${after}`;
       });
     });
     visit(tree, (node) => {
@@ -132,9 +160,10 @@ var remarkResolveImages = (options) => {
       const srcAttr = jsx.attributes.find((a) => a.type === "mdxJsxAttribute" && a.name === "src");
       if (!srcAttr?.value || typeof srcAttr.value !== "string")
         return;
-      srcAttr.value = resolveUrl(srcAttr.value, dir);
-      collect(srcAttr.value);
-      srcAttr.value = optimizeUrl(srcAttr.value, optimize);
+      const { base: jsxBase, params: jsxParams } = parseImageParams(srcAttr.value);
+      const jsxResolved = resolveUrl(jsxBase, dir);
+      collect(jsxResolved);
+      srcAttr.value = optimizeUrl(appendParams(jsxResolved, jsxParams), optimize);
     });
     visit(tree, "element", (node) => {
       if (node.tagName !== "img")
@@ -142,9 +171,10 @@ var remarkResolveImages = (options) => {
       const src = node.properties?.src;
       if (typeof src !== "string")
         return;
-      node.properties.src = resolveUrl(src, dir);
-      collect(node.properties.src);
-      node.properties.src = optimizeUrl(node.properties.src, optimize);
+      const { base: elBase, params: elParams } = parseImageParams(src);
+      const elResolved = resolveUrl(elBase, dir);
+      collect(elResolved);
+      node.properties.src = optimizeUrl(appendParams(elResolved, elParams), optimize);
     });
     file.data.images = images;
   };
@@ -877,6 +907,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.0",
+  "version": "0.12.2",
   "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/remark-resolve-images.ts

@@ -7,6 +7,30 @@ import type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute } from 'mdas
 import { MdxNodeType } from './mdx-utils'
 import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from './image-utils'
 
+interface ImageParams {
+  w?: number
+  q?: number
+}
+
+function parseImageParams(src: string): { base: string; params: ImageParams } {
+  const qIdx = src.indexOf('?')
+  if (qIdx === -1) return { base: src, params: {} }
+  const base = src.slice(0, qIdx)
+  const search = new URLSearchParams(src.slice(qIdx + 1))
+  const params: ImageParams = {}
+  if (search.has('w')) params.w = Number.parseInt(search.get('w')!, 10)
+  if (search.has('q')) params.q = Number.parseInt(search.get('q')!, 10)
+  return { base, params }
+}
+
+function appendParams(url: string, params: ImageParams): string {
+  if (!params.w && !params.q) return url
+  const qs = new URLSearchParams()
+  if (params.w) qs.set('w', String(params.w))
+  if (params.q) qs.set('q', String(params.q))
+  return `${url}?${qs}`
+}
+
 function resolveUrl(src: string, dir: string): string {
   const normalized = src.replace(/\\/g, '/')
   if (/^[a-z][a-z0-9+\-.]*:/i.test(normalized)) return normalized
@@ -23,8 +47,11 @@ interface RemarkResolveImagesOptions {
 }
 
 function optimizeUrl(url: string, optimize: boolean): string {
-  if (optimize && isLocalImage(url) && !isSvg(url)) return buildOptimizedUrl(url, DEFAULT_WIDTH)
-  return url
+  const { base, params } = parseImageParams(url)
+  const width = params.w || DEFAULT_WIDTH
+  const quality = params.q
+  if (optimize && isLocalImage(base) && !isSvg(base)) return buildOptimizedUrl(base, width, quality)
+  return base
 }
 
 const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
@@ -50,18 +77,20 @@ const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) =>
 
     visit(tree, 'image', (node: Image) => {
       if (!node.url) return
-      node.url = resolveUrl(node.url, dir)
-      collect(node.url)
-      node.url = optimizeUrl(node.url, optimize)
+      const { base, params } = parseImageParams(node.url)
+      const resolved = resolveUrl(base, dir)
+      collect(resolved)
+      node.url = optimizeUrl(appendParams(resolved, params), optimize)
     })
 
     visit(tree, 'html', (node: Html) => {
       node.value = node.value.replace(
         /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi,
         (_, before, src, after) => {
-          const resolved = resolveUrl(src, dir)
+          const { base, params } = parseImageParams(src)
+          const resolved = resolveUrl(base, dir)
           collect(resolved)
-          return `${before}${optimizeUrl(resolved, optimize)}${after}`
+          return `${before}${optimizeUrl(appendParams(resolved, params), optimize)}${after}`
         }
       )
     })
@@ -72,18 +101,20 @@ const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) =>
       if (jsx.name !== 'img') return
       const srcAttr = jsx.attributes.find((a): a is MdxJsxAttribute => a.type === 'mdxJsxAttribute' && a.name === 'src')
       if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
-      srcAttr.value = resolveUrl(srcAttr.value, dir)
-      collect(srcAttr.value)
-      srcAttr.value = optimizeUrl(srcAttr.value, optimize)
+      const { base: jsxBase, params: jsxParams } = parseImageParams(srcAttr.value)
+      const jsxResolved = resolveUrl(jsxBase, dir)
+      collect(jsxResolved)
+      srcAttr.value = optimizeUrl(appendParams(jsxResolved, jsxParams), optimize)
     })
 
     visit(tree, 'element', (node: Element) => {
       if (node.tagName !== 'img') return
       const src = node.properties?.src
       if (typeof src !== 'string') return
-      node.properties.src = resolveUrl(src, dir)
-      collect(node.properties.src as string)
-      node.properties.src = optimizeUrl(node.properties.src as string, optimize)
+      const { base: elBase, params: elParams } = parseImageParams(src)
+      const elResolved = resolveUrl(elBase, dir)
+      collect(elResolved)
+      node.properties.src = optimizeUrl(appendParams(elResolved, elParams), optimize)
     })
 
     file.data.images = images

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/server/api/image.test.ts

@@ -48,6 +48,12 @@ describe('cacheKey', () => {
     expect(a).not.toBe(b);
   });
 
+  test('returns different keys for different mtime', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp', 1000);
+    const b = cacheKey('/_content/img.png', 640, 75, 'webp', 2000);
+    expect(a).not.toBe(b);
+  });
+
   test('key ends with format extension', () => {
     expect(cacheKey('/_content/img.png', 640, 75, 'webp')).toMatch(/\.webp$/);
     expect(cacheKey('/_content/img.png', 640, 75, 'avif')).toMatch(/\.avif$/);

package/src/server/api/image.ts

@@ -6,10 +6,9 @@ import { useStorage } from 'nitro/storage'
 import sharp from 'sharp'
 import { StatusCodes } from 'http-status-codes'
 import { safePath } from '@/server/utils/safe-path'
-import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_QUALITY } from '@/lib/image-utils'
+import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_WIDTH, DEFAULT_QUALITY, isLocalImage, isSvg } from '@/lib/image-utils'
 
-const STORAGE_KEY = 'image-cache'
-const MAX_CACHE_ENTRIES = 500
+export const STORAGE_KEY = 'image-cache'
 
 const inflight = new Map<string, Promise<Buffer>>()
 
@@ -29,8 +28,8 @@ export const MIME: Record<string, string> = {
   '.webp': 'image/webp',
 }
 
-export function cacheKey(url: string, w: number, q: number, format: OutputFormat): string {
-  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}`).digest('hex').slice(0, 16)
+export function cacheKey(url: string, w: number, q: number, format: OutputFormat, mtime?: number): string {
+  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}:${mtime ?? 0}`).digest('hex').slice(0, 16)
   return `${hash}.${format}`
 }
 
@@ -42,11 +41,17 @@ function snapQuality(q: number): number {
   return closest;
 }
 
-async function evictIfNeeded(storage: ReturnType<typeof useStorage>) {
-  const keys = await storage.getKeys()
-  if (keys.length <= MAX_CACHE_ENTRIES) return
-  const toRemove = keys.slice(0, keys.length - MAX_CACHE_ENTRIES)
-  await Promise.all(toRemove.map(k => storage.removeItem(k)))
+export async function optimizeImage(
+  filePath: string,
+  w: number,
+  q: number,
+  format: OutputFormat,
+): Promise<Buffer> {
+  const source = await fs.readFile(filePath);
+  const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true });
+  if (format === 'avif') return pipeline.avif({ quality: q }).toBuffer();
+  if (format === 'webp') return pipeline.webp({ quality: q }).toBuffer();
+  return pipeline.toBuffer();
 }
 
 export default defineHandler(async event => {
@@ -90,7 +95,11 @@ export default defineHandler(async event => {
   const originalMime = MIME[ext] ?? 'application/octet-stream'
   const contentType = format === 'original' ? originalMime : `image/${format}`
 
-  const key = cacheKey(url, w, q, format)
+  const stat = await fs.stat(filePath).catch(() => null)
+  if (!stat) {
+    throw new HTTPError({ status: StatusCodes.NOT_FOUND, message: 'Not Found' })
+  }
+  const key = cacheKey(url, w, q, format, stat.mtimeMs)
 
   const cached = await storage.getItemRaw<Buffer>(key)
   if (cached) {
@@ -116,16 +125,8 @@ export default defineHandler(async event => {
   }
 
   const work = (async () => {
-    const source = await fs.readFile(filePath)
-    const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true })
-    const optimized = format === 'avif'
-      ? await pipeline.avif({ quality: q }).toBuffer()
-      : format === 'webp'
-        ? await pipeline.webp({ quality: q }).toBuffer()
-        : await pipeline.toBuffer()
-
+    const optimized = await optimizeImage(filePath, w, q, format)
     await storage.setItemRaw(key, optimized)
-    await evictIfNeeded(storage)
     return optimized
   })()
 
@@ -154,3 +155,45 @@ export default defineHandler(async event => {
     inflight.delete(key)
   }
 })
+
+export async function warmupImageCache() {
+  const { getPages, getPageImages } = await import('@/lib/source');
+  // biome-ignore lint/correctness/useHookAtTopLevel: useStorage is a Nitro DI accessor, not a React hook
+  const storage = useStorage(STORAGE_KEY);
+  const contentDir = __CHRONICLE_CONTENT_DIR__;
+  const format = 'webp' as const;
+  const w = DEFAULT_WIDTH;
+  const q = DEFAULT_QUALITY;
+
+  const pages = await getPages();
+  const seen = new Set<string>();
+  let warmed = 0;
+
+  for (const page of pages) {
+    for (const url of getPageImages(page)) {
+      if (!isLocalImage(url) || isSvg(url) || seen.has(url)) continue;
+      seen.add(url);
+
+      const relativePath = url.replace(/^\/_content\//, '');
+      const filePath = safePath(contentDir, `/${relativePath}`);
+      if (!filePath) continue;
+
+      const stat = await fs.stat(filePath).catch(() => null);
+      if (!stat) continue;
+
+      const key = cacheKey(url, w, q, format, stat.mtimeMs);
+      const cached = await storage.getItemRaw(key);
+      if (cached) continue;
+
+      try {
+        const optimized = await optimizeImage(filePath, w, q, format);
+        await storage.setItemRaw(key, optimized);
+        warmed++;
+      } catch { /* skip unprocessable */ }
+    }
+  }
+
+  if (warmed > 0) {
+    console.log(`[image-warmup] cached ${warmed} images as webp@${w}w`);
+  }
+}

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/api/ready.ts

@@ -1,9 +1,11 @@
 import { defineHandler } from 'nitro';
 import { ensureIndex, isSearchReady } from './search';
+import { warmupImageCache } from './image';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 
 export default defineHandler(async () => {
   ensureIndex(LATEST_CONTEXT).catch(e => console.error('[search:index]', e));
+  warmupImageCache().catch(e => console.error('[image-warmup]', e));
 
   if (!isSearchReady()) {
     return new Response(JSON.stringify({ status: 'not_ready', search: false }), {

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,
@@ -169,5 +195,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/themes/default/Layout.module.css

@@ -76,7 +76,9 @@
 
 .topLinks {
   width: 100%;
-  margin-bottom: var(--rs-space-7);
+  display: flex;
+  flex-direction: column;
+  gap: 0;
 }
 
 .topLinkItem {
@@ -135,7 +137,7 @@
 .cardWrapper {
   flex: 1;
   display: flex;
-  padding: 0 0 var(--rs-space-2) 0;
+  padding: 0;
   min-height: 0;
   background: var(--rs-color-background-base-secondary);
 }
@@ -154,7 +156,7 @@
   align-items: center;
   justify-content: space-between;
   height: var(--navbar-height);
-  padding: var(--rs-space-4) var(--rs-space-7);
+  padding: var(--rs-space-4) var(--rs-space-8);
   background: var(--rs-color-background-base-primary);
   border-bottom: 0.5px solid var(--rs-color-border-base-primary);
   backdrop-filter: blur(1px);
@@ -172,7 +174,7 @@
 
 .groupItems {
   padding-left: 0;
-  padding-bottom: var(--rs-space-3);
+  padding-bottom: 0;
   gap: 0;
 }
 
@@ -190,6 +192,9 @@
 
 .navGroup .navGroupHeader {
   margin: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
 }
 
 .navGroup[data-depth='1'] .navGroupHeader {

package/src/themes/default/Layout.tsx

@@ -62,8 +62,6 @@ function renderConfigIcon(
   return <img src={icon} alt={alt} className={styles.configIcon} />;
 }
 
-let savedScrollTop = 0;
-
 export function Layout({
   children,
   config,
@@ -97,22 +95,20 @@ export function Layout({
   );
 
   useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    const onScroll = () => {
-      savedScrollTop = el.scrollTop;
-    };
-    el.addEventListener('scroll', onScroll);
-    return () => el.removeEventListener('scroll', onScroll);
-  }, []);
-
-  useEffect(() => {
-    const el = scrollRef.current;
-    if (el)
-      requestAnimationFrame(() => {
-        el.scrollTop = savedScrollTop;
-      });
+    const timer = setTimeout(() => {
+      const container = document.querySelector<HTMLElement>(`.${styles.sidebarMain}`);
+      if (!container) return;
+      const allActive = container.querySelectorAll<HTMLElement>('[data-active="true"]');
+      const activeItem = allActive[allActive.length - 1];
+      if (!activeItem) return;
+      const containerRect = container.getBoundingClientRect();
+      const itemRect = activeItem.getBoundingClientRect();
+      if (itemRect.top < containerRect.top || itemRect.bottom > containerRect.bottom) {
+        container.scrollTop += itemRect.top - containerRect.top - containerRect.height / 2 + itemRect.height / 2;
+      }
+    }, 100);
     setMobileSidebarOpen(false);
+    return () => clearTimeout(timer);
   }, [pathname]);
 
   return (
@@ -436,6 +432,7 @@ function ApiSidebarNode({ item, pathname }: { item: Node; pathname: string }) {
       align='center'
       gap={3}
       className={`${styles.apiItem} ${isActive ? styles.apiItemActive : ''}`}
+      data-active={isActive}
       render={<RouterLink to={href} />}
     >
       <span className={styles.apiItemName}>{item.name}</span>