From b9955101b7e5308369e2c74984b2b31b681b5745 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 11:34:12 +0530
Subject: [PATCH 1/9] feat: add prev/next nav fields to Page type

Prepare Page type for backend-provided prev/next links used by the
docs sub-navbar. Adds PageNavLink/PageNav types, extends Page via
extends PageNav, unifies PageData with Page in page context, and
threads null placeholders through SSR + hydration until backend
computes real values.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/chronicle/src/lib/page-context.tsx   | 21 +++++++------------
 packages/chronicle/src/pages/DocsPage.tsx     |  7 +------
 .../chronicle/src/server/entry-client.tsx     |  6 +++++-
 .../chronicle/src/server/entry-server.tsx     |  4 ++++
 packages/chronicle/src/types/content.ts       | 12 ++++++++++-
 5 files changed, 28 insertions(+), 22 deletions(-)

diff --git a/packages/chronicle/src/lib/page-context.tsx b/packages/chronicle/src/lib/page-context.tsx
index a421459..b88de29 100644
--- a/packages/chronicle/src/lib/page-context.tsx
+++ b/packages/chronicle/src/lib/page-context.tsx
@@ -7,21 +7,14 @@ import {
 } from 'react';
 import { useLocation } from 'react-router';
 import type { ApiSpec } from '@/lib/openapi';
-import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+import type { ChronicleConfig, Frontmatter, Page, Root, TableOfContents } from '@/types';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
-interface PageData {
-  slug: string[];
-  frontmatter: Frontmatter;
-  content: ReactNode;
-  toc: TableOfContents;
-}
-
 interface PageContextValue {
   config: ChronicleConfig;
   tree: Root;
-  page: PageData | null;
+  page: Page | null;
   errorStatus: number | null;
   apiSpecs: ApiSpec[];
 }
@@ -46,7 +39,7 @@ export function usePageContext(): PageContextValue {
 interface PageProviderProps {
   initialConfig: ChronicleConfig;
   initialTree: Root;
-  initialPage: PageData | null;
+  initialPage: Page | null;
   initialApiSpecs: ApiSpec[];
   loadMdx: MdxLoader;
   children: ReactNode;
@@ -56,7 +49,7 @@ function isApisRoute(pathname: string): boolean {
   return pathname === '/apis' || pathname.startsWith('/apis/');
 }
 
-function getInitialErrorStatus(page: PageData | null, pathname: string): number | null {
+function getInitialErrorStatus(page: Page | null, pathname: string): number | null {
   if (page) return null;
   if (pathname === '/' || isApisRoute(pathname)) return null;
   return 404;
@@ -72,7 +65,7 @@ export function PageProvider({
 }: PageProviderProps) {
   const { pathname } = useLocation();
   const [tree] = useState<Root>(initialTree);
-  const [page, setPage] = useState<PageData | null>(initialPage);
+  const [page, setPage] = useState<Page | null>(initialPage);
   const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, pathname));
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
   const [currentPath, setCurrentPath] = useState(pathname);
@@ -112,12 +105,12 @@ export function PageProvider({
         }
         return res.json();
       })
-      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string } | undefined) => {
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string; prev: Page['prev']; next: Page['next'] } | undefined) => {
         if (cancelled.current || !data) return;
         const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
         if (cancelled.current) return;
         setErrorStatus(null);
-        setPage({ slug, frontmatter: data.frontmatter, content, toc });
+        setPage({ slug, frontmatter: data.frontmatter, content, toc, prev: data.prev, next: data.next });
       })
       .catch(() => {
         if (!cancelled.current) {
diff --git a/packages/chronicle/src/pages/DocsPage.tsx b/packages/chronicle/src/pages/DocsPage.tsx
index e1710b4..35ce71f 100644
--- a/packages/chronicle/src/pages/DocsPage.tsx
+++ b/packages/chronicle/src/pages/DocsPage.tsx
@@ -32,12 +32,7 @@ export function DocsPage({ slug }: DocsPageProps) {
         }}
       />
       <Page
-        page={{
-          slug: page.slug,
-          frontmatter: page.frontmatter,
-          content: page.content,
-          toc: page.toc
-        }}
+        page={page}
         config={config}
         tree={tree}
       />
diff --git a/packages/chronicle/src/server/entry-client.tsx b/packages/chronicle/src/server/entry-client.tsx
index f972f85..f5a9032 100644
--- a/packages/chronicle/src/server/entry-client.tsx
+++ b/packages/chronicle/src/server/entry-client.tsx
@@ -5,7 +5,7 @@ import { BrowserRouter } from 'react-router';
 import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
 import { mdxComponents } from '@/components/mdx';
 import { PageProvider } from '@/lib/page-context';
-import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+import type { ChronicleConfig, Frontmatter, PageNavLink, Root, TableOfContents } from '@/types';
 import type { ApiSpec } from '@/lib/openapi';
 import type { ReactNode } from 'react';
 import { App } from './App';
@@ -17,6 +17,8 @@ interface EmbeddedData {
   frontmatter: Frontmatter;
   relativePath: string;
   originalPath?: string;
+  prev: PageNavLink | null;
+  next: PageNavLink | null;
 }
 
 const contentModules = import.meta.glob<{ default?: React.ComponentType<any>; toc?: TableOfContents }>(
@@ -60,6 +62,8 @@ async function hydrate() {
       ? {
           slug: embedded!.slug,
           frontmatter: embedded!.frontmatter,
+          prev: embedded!.prev,
+          next: embedded!.next,
           ...(await loadMdxModule(mdxPath)),
         }
       : null;
diff --git a/packages/chronicle/src/server/entry-server.tsx b/packages/chronicle/src/server/entry-server.tsx
index fe23e1a..6a5e3e7 100644
--- a/packages/chronicle/src/server/entry-server.tsx
+++ b/packages/chronicle/src/server/entry-server.tsx
@@ -43,6 +43,8 @@ export default {
             ? React.createElement(mdxModule.default, { components: mdxComponents })
             : null,
           toc: mdxModule?.toc ?? [],
+          prev: null,
+          next: null,
         }
       : null;
 
@@ -53,6 +55,8 @@ export default {
       frontmatter: pageData?.frontmatter ?? null,
       relativePath,
       originalPath,
+      prev: pageData?.prev ?? null,
+      next: pageData?.next ?? null,
     };
     const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c');
 
diff --git a/packages/chronicle/src/types/content.ts b/packages/chronicle/src/types/content.ts
index 0ca7ecf..6f36f53 100644
--- a/packages/chronicle/src/types/content.ts
+++ b/packages/chronicle/src/types/content.ts
@@ -12,7 +12,17 @@ export interface Frontmatter {
   lastModified?: string
 }
 
-export interface Page {
+export interface PageNavLink {
+  url: string
+  title: string
+}
+
+export interface PageNav {
+  prev: PageNavLink | null
+  next: PageNavLink | null
+}
+
+export interface Page extends PageNav {
   slug: string[]
   frontmatter: Frontmatter
   content: ReactNode

From 2fe9b61d6d72669af26a4647b9f8be0028c7c5c2 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 11:45:46 +0530
Subject: [PATCH 2/9] fix: add std-env as root dep to unblock nitro beta

nitro@3.0.260311-beta lists std-env in devDependencies but its
runtime imports it. Node ESM resolution from nitro's isolated
cache path fails without std-env at top-level node_modules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 bun.lock     | 5 +++++
 package.json | 3 +++
 2 files changed, 8 insertions(+)

diff --git a/bun.lock b/bun.lock
index d0cf6f1..8380cd4 100644
--- a/bun.lock
+++ b/bun.lock
@@ -4,6 +4,9 @@
   "workspaces": {
     "": {
       "name": "chronicle",
+      "dependencies": {
+        "std-env": "^4.0.0",
+      },
     },
     "packages/chronicle": {
       "name": "@raystack/chronicle",
@@ -1234,6 +1237,8 @@
 
     "srvx": ["srvx@0.11.12", "", { "bin": { "srvx": "bin/srvx.mjs" } }, "sha512-AQfrGqntqVPXgP03pvBDN1KyevHC+KmYVqb8vVf4N+aomQqdhaZxjvoVp+AOm4u6x+GgNQY3MVzAUIn+TqwkOA=="],
 
+    "std-env": ["std-env@4.1.0", "", {}, "sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ=="],
+
     "string.prototype.codepointat": ["string.prototype.codepointat@0.2.1", "", {}, "sha512-2cBVCj6I4IOvEnjgO/hWqXjqBGsY+zwPmHl12Srk9IXSZ56Jwwmy+66XO5Iut/oQVR7t5ihYdLB0GMa4alEUcg=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
diff --git a/package.json b/package.json
index 6421a8f..0effbab 100644
--- a/package.json
+++ b/package.json
@@ -13,5 +13,8 @@
     "dev:docs": "./packages/chronicle/bin/chronicle.js dev --config docs/chronicle.yaml",
     "start:docs": "./packages/chronicle/bin/chronicle.js start --config docs/chronicle.yaml",
     "build:docs": "./packages/chronicle/bin/chronicle.js build --config docs/chronicle.yaml"
+  },
+  "dependencies": {
+    "std-env": "^4.0.0"
   }
 }

From 70e9404ec6d121b283c47c5e489ae5f03ae3a7d4 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 11:45:51 +0530
Subject: [PATCH 3/9] feat: restructure default theme layout with tab bar

Drop the top Navbar; move navigation into a per-section tab bar
alongside the sidebar. Resize sidebar to 262px, swap button-based
nav links for pill-style tabs using mini typography tokens.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../src/themes/default/Layout.module.css      | 80 +++++++++----------
 .../chronicle/src/themes/default/Layout.tsx   | 72 +++++++----------
 2 files changed, 68 insertions(+), 84 deletions(-)

diff --git a/packages/chronicle/src/themes/default/Layout.module.css b/packages/chronicle/src/themes/default/Layout.module.css
index dadbe5d..cccb5f0 100644
--- a/packages/chronicle/src/themes/default/Layout.module.css
+++ b/packages/chronicle/src/themes/default/Layout.module.css
@@ -2,76 +2,70 @@
   min-height: 100vh;
 }
 
-.header {
-  border-bottom: 1px solid var(--rs-color-border-base-primary);
-}
-
-.search {
-  margin-left: var(--rs-space-5);
-}
-
 .body {
   flex: 1;
 }
 
 .sidebar {
-  width: 260px;
+  width: 262px;
   position: sticky;
   top: 0;
   height: 100vh;
 }
 
-.content {
+.mainArea {
   flex: 1;
-  padding: var(--rs-space-9);
+  min-width: 0;
 }
 
-.sidebarList {
-  list-style: none;
-  padding: 0;
-  margin: 0;
-}
-
-.separator {
-  height: 1px;
-  background: var(--rs-color-border-base-primary);
-  margin: var(--rs-space-3) 0;
-}
-
-.folder {
-  margin-bottom: var(--rs-space-3);
-}
-
-.folderLabel {
-  font-weight: 500;
-  font-size: 0.875rem;
-  color: var(--rs-color-text-base-secondary);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
+.tabBar {
+  display: flex;
+  align-items: center;
+  height: 48px;
+  padding: 0 var(--rs-space-2);
+  background: var(--rs-color-background-base-secondary);
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
 }
 
-.folder > .sidebarList {
-  margin-top: var(--rs-space-2);
-  padding-left: var(--rs-space-4);
+.tabs {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-3);
 }
 
-.navButton {
+.tab {
   display: flex;
   align-items: center;
-  height: 32px;
-  padding: 0 var(--rs-space-4);
-  border: 1px solid var(--rs-color-border-base-primary);
+  gap: var(--rs-space-2);
+  padding: var(--rs-space-2) var(--rs-space-3);
+  border: 0.5px solid var(--rs-color-border-base-primary);
   border-radius: var(--rs-radius-2);
-  font-size: var(--rs-font-size-small);
+  font-size: var(--rs-font-size-mini);
   font-weight: var(--rs-font-weight-medium);
-  color: var(--rs-color-foreground-base-primary);
+  letter-spacing: var(--rs-letter-spacing-mini);
+  line-height: var(--rs-line-height-mini);
+  color: var(--rs-color-foreground-base-secondary);
   text-decoration: none;
+  white-space: nowrap;
+  cursor: pointer;
 }
 
-.navButton:hover {
+.tab:hover {
+  color: var(--rs-color-foreground-base-primary);
   background: var(--rs-color-background-base-primary-hover);
 }
 
+.tabActive {
+  background: var(--rs-color-background-neutral-primary);
+  border-color: var(--rs-color-border-base-secondary);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.content {
+  flex: 1;
+  padding: var(--rs-space-9);
+}
+
 .groupItems {
   padding-left: var(--rs-space-4);
 }
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index 625784d..37438a1 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -1,19 +1,17 @@
 import { RectangleStackIcon } from '@heroicons/react/24/outline';
 import {
-  Button,
+  DocumentTextIcon,
+  CodeBracketSquareIcon
+} from '@heroicons/react/24/outline';
+import {
   Flex,
-  Headline,
-  Link,
-  Navbar,
   Sidebar
 } from '@raystack/apsara';
 import { cx } from 'class-variance-authority';
 import { useEffect, useRef } from 'react';
 import { Link as RouterLink, useLocation } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
-import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Footer } from '@/components/ui/footer';
-import { Search } from '@/components/ui/search';
 import type { Node } from 'fumadocs-core/page-tree';
 import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
@@ -37,6 +35,7 @@ export function Layout({
 }: ThemeLayoutProps) {
   const { pathname } = useLocation();
   const scrollRef = useRef<HTMLDivElement>(null);
+  const isApiRoute = pathname.startsWith('/apis');
 
   useEffect(() => {
     const el = scrollRef.current;
@@ -58,38 +57,6 @@ export function Layout({
 
   return (
     <Flex direction='column' className={cx(styles.layout, classNames?.layout)}>
-      <Navbar className={styles.header}>
-        <Navbar.Start>
-          <RouterLink
-            to='/'
-            style={{ textDecoration: 'none', color: 'inherit' }}
-          >
-            <Headline size='small' weight='medium' as='h1'>
-              {config.title}
-            </Headline>
-          </RouterLink>
-        </Navbar.Start>
-        <Navbar.End>
-          <Flex gap='medium' align='center' className={styles.navActions}>
-            {config.api?.map(api => (
-              <RouterLink
-                key={api.basePath}
-                to={api.basePath}
-                className={styles.navButton}
-              >
-                {api.name} API
-              </RouterLink>
-            ))}
-            {config.navigation?.links?.map(link => (
-              <Link key={link.href} href={link.href}>
-                {link.label}
-              </Link>
-            ))}
-            {config.search?.enabled && <Search />}
-          </Flex>
-          <ClientThemeSwitcher size={16} />
-        </Navbar.End>
-      </Navbar>
       <Flex className={cx(styles.body, classNames?.body)}>
         <Sidebar
           defaultOpen
@@ -106,9 +73,32 @@ export function Layout({
             ))}
           </Sidebar.Main>
         </Sidebar>
-        <main className={cx(styles.content, classNames?.content)}>
-          {children}
-        </main>
+        <Flex direction='column' className={styles.mainArea}>
+          <nav className={styles.tabBar}>
+            <div className={styles.tabs}>
+              <RouterLink
+                to='/'
+                className={cx(styles.tab, !isApiRoute && styles.tabActive)}
+              >
+                <DocumentTextIcon width={12} height={12} />
+                <span>Docs</span>
+              </RouterLink>
+              {config.api?.map(api => (
+                <RouterLink
+                  key={api.basePath}
+                  to={api.basePath}
+                  className={cx(styles.tab, isApiRoute && styles.tabActive)}
+                >
+                  <CodeBracketSquareIcon width={12} height={12} />
+                  <span>{api.name} API</span>
+                </RouterLink>
+              ))}
+            </div>
+          </nav>
+          <main className={cx(styles.content, classNames?.content)}>
+            {children}
+          </main>
+        </Flex>
       </Flex>
       <Footer config={config.footer} />
     </Flex>

From fcbe6c047a43e4f27c0889e4cceaea46631cfa8b Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 11:46:29 +0530
Subject: [PATCH 4/9] chore: switch docs theme to default

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/chronicle.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/chronicle.yaml b/docs/chronicle.yaml
index 5a3de82..83bb1e7 100644
--- a/docs/chronicle.yaml
+++ b/docs/chronicle.yaml
@@ -3,7 +3,7 @@ description: Config-driven documentation framework
 content: .
 
 theme:
-  name: paper
+  name: default
 
 navigation:
   links:

From ff911ef58671281c0679815e27bc7397325c0587 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 12:03:46 +0530
Subject: [PATCH 5/9] feat: compute page prev/next on the server

Add getPageNav helper that flattens the page tree and returns the
adjacent PageNavLinks for a slug. Both the /api/page handler and SSR
pageData now populate prev/next so the client can render navigation
without re-flattening the tree.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/chronicle/src/lib/source.ts          | 19 ++++++++++++++++++-
 packages/chronicle/src/server/api/page.ts     |  6 +++++-
 .../chronicle/src/server/entry-server.tsx     |  9 +++++----
 3 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts
index 0d9e155..2fd1e26 100644
--- a/packages/chronicle/src/lib/source.ts
+++ b/packages/chronicle/src/lib/source.ts
@@ -1,8 +1,9 @@
 import { loader } from 'fumadocs-core/source';
+import { flattenTree } from 'fumadocs-core/page-tree';
 import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
 import type { MDXContent } from 'mdx/types';
 import type { TableOfContents } from 'fumadocs-core/toc';
-import type { Frontmatter } from '@/types';
+import type { Frontmatter, PageNav, PageNavLink } from '@/types';
 
 const CONTENT_PREFIX = '../../.content/';
 
@@ -105,6 +106,22 @@ export async function getPage(slugs?: string[]) {
   return s.getPage(slugs);
 }
 
+export async function getPageNav(slug: string[]): Promise<PageNav> {
+  const tree = await getPageTree();
+  const pages = flattenTree(tree.children);
+  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`;
+  const i = pages.findIndex(p => p.url === url);
+  if (i < 0) return { prev: null, next: null };
+  const toLink = (p: (typeof pages)[number]): PageNavLink => ({
+    url: p.url,
+    title: String(p.name ?? '')
+  });
+  return {
+    prev: i > 0 ? toLink(pages[i - 1]) : null,
+    next: i < pages.length - 1 ? toLink(pages[i + 1]) : null
+  };
+}
+
 export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
   const d = page.data as Record<string, unknown>;
   return {
diff --git a/packages/chronicle/src/server/api/page.ts b/packages/chronicle/src/server/api/page.ts
index bfb43aa..568d6aa 100644
--- a/packages/chronicle/src/server/api/page.ts
+++ b/packages/chronicle/src/server/api/page.ts
@@ -1,5 +1,5 @@
 import { defineHandler, HTTPError } from 'nitro';
-import { getPage, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { getPage, getPageNav, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 
 export default defineHandler(async event => {
   const slugParam = event.url.searchParams.get('slug') ?? '';
@@ -10,9 +10,13 @@ export default defineHandler(async event => {
     throw new HTTPError({ status: 404, message: 'Page not found' });
   }
 
+  const nav = await getPageNav(slug);
+
   return {
     frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
     relativePath: getRelativePath(page),
     originalPath: getOriginalPath(page),
+    prev: nav.prev,
+    next: nav.next,
   };
 });
diff --git a/packages/chronicle/src/server/entry-server.tsx b/packages/chronicle/src/server/entry-server.tsx
index 6a5e3e7..2d4536c 100644
--- a/packages/chronicle/src/server/entry-server.tsx
+++ b/packages/chronicle/src/server/entry-server.tsx
@@ -8,7 +8,7 @@ import { mdxComponents } from '@/components/mdx';
 import { loadConfig } from '@/lib/config';
 import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
-import { getPageTree, getPage, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
 import { useNitroApp } from 'nitro/app';
 import { App } from './App';
 
@@ -26,9 +26,10 @@ export default {
       ? await loadApiSpecs(config.api).catch(() => [])
       : [];
 
-    const [tree, page] = await Promise.all([
+    const [tree, page, nav] = await Promise.all([
       getPageTree(),
       getPage(slug),
+      getPageNav(slug),
     ]);
 
     const relativePath = page ? getRelativePath(page) : null;
@@ -43,8 +44,8 @@ export default {
             ? React.createElement(mdxModule.default, { components: mdxComponents })
             : null,
           toc: mdxModule?.toc ?? [],
-          prev: null,
-          next: null,
+          prev: nav.prev,
+          next: nav.next,
         }
       : null;
 

From bd031a8f560dfab97c8c64b8588abdbff279b8b4 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 12:07:20 +0530
Subject: [PATCH 6/9] feat: wrap content in card with prev/next sub-navbar

Default theme now renders the main content inside a rounded, bordered
card with a sub-navbar at the top containing prev/next IconButtons
driven by the server-provided page nav, followed by breadcrumbs.
Breadcrumbs move out of Page.tsx since the Layout owns the chrome.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../src/themes/default/Layout.module.css      | 37 +++++++++++-
 .../chronicle/src/themes/default/Layout.tsx   | 58 +++++++++++++++----
 .../chronicle/src/themes/default/Page.tsx     |  4 +-
 3 files changed, 84 insertions(+), 15 deletions(-)

diff --git a/packages/chronicle/src/themes/default/Layout.module.css b/packages/chronicle/src/themes/default/Layout.module.css
index cccb5f0..afd2d2b 100644
--- a/packages/chronicle/src/themes/default/Layout.module.css
+++ b/packages/chronicle/src/themes/default/Layout.module.css
@@ -61,9 +61,44 @@
   color: var(--rs-color-foreground-base-primary);
 }
 
+.cardWrapper {
+  flex: 1;
+  display: flex;
+  padding: 0 var(--rs-space-2) var(--rs-space-2);
+  min-height: 0;
+}
+
+.card {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  background: var(--rs-color-background-base-primary);
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-4);
+  box-shadow:
+    0 1px 2px 0 rgba(0, 0, 0, 0.04),
+    0 2px 4px 0 rgba(0, 0, 0, 0.04);
+  overflow: clip;
+}
+
+.subNav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 48px;
+  padding: var(--rs-space-4) var(--rs-space-7);
+  background: var(--rs-color-background-base-primary);
+  border-bottom: 0.5px solid var(--rs-color-border-base-primary);
+  backdrop-filter: blur(1px);
+}
+
+.subNavLeft {
+  min-width: 0;
+}
+
 .content {
   flex: 1;
-  padding: var(--rs-space-9);
+  padding: var(--rs-space-9) var(--rs-space-7);
 }
 
 .groupItems {
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index 37438a1..d0d8cb9 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -1,17 +1,18 @@
-import { RectangleStackIcon } from '@heroicons/react/24/outline';
 import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  CodeBracketSquareIcon,
   DocumentTextIcon,
-  CodeBracketSquareIcon
+  RectangleStackIcon
 } from '@heroicons/react/24/outline';
-import {
-  Flex,
-  Sidebar
-} from '@raystack/apsara';
+import { Flex, IconButton, Sidebar } from '@raystack/apsara';
 import { cx } from 'class-variance-authority';
-import { useEffect, useRef } from 'react';
-import { Link as RouterLink, useLocation } from 'react-router';
+import { useEffect, useMemo, useRef } from 'react';
+import { Link as RouterLink, useLocation, useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
+import { Breadcrumbs } from '@/components/ui/breadcrumbs';
 import { Footer } from '@/components/ui/footer';
+import { usePageContext } from '@/lib/page-context';
 import type { Node } from 'fumadocs-core/page-tree';
 import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
@@ -34,8 +35,16 @@ export function Layout({
   classNames
 }: ThemeLayoutProps) {
   const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const { page } = usePageContext();
   const scrollRef = useRef<HTMLDivElement>(null);
   const isApiRoute = pathname.startsWith('/apis');
+  const { prev, next } = page ?? { prev: null, next: null };
+
+  const slug = useMemo(
+    () => (pathname === '/' ? [] : pathname.split('/').filter(Boolean)),
+    [pathname]
+  );
 
   useEffect(() => {
     const el = scrollRef.current;
@@ -95,9 +104,36 @@ export function Layout({
               ))}
             </div>
           </nav>
-          <main className={cx(styles.content, classNames?.content)}>
-            {children}
-          </main>
+          <div className={styles.cardWrapper}>
+            <div className={styles.card}>
+              <nav className={styles.subNav}>
+                <Flex align='center' gap='small' className={styles.subNavLeft}>
+                  <Flex align='center' gap='extra-small'>
+                    <IconButton
+                      size={2}
+                      disabled={!prev}
+                      onClick={() => prev && navigate(prev.url)}
+                      aria-label='Previous page'
+                    >
+                      <ArrowLeftIcon width={14} height={14} />
+                    </IconButton>
+                    <IconButton
+                      size={2}
+                      disabled={!next}
+                      onClick={() => next && navigate(next.url)}
+                      aria-label='Next page'
+                    >
+                      <ArrowRightIcon width={14} height={14} />
+                    </IconButton>
+                  </Flex>
+                  <Breadcrumbs slug={slug} tree={tree} />
+                </Flex>
+              </nav>
+              <main className={cx(styles.content, classNames?.content)}>
+                {children}
+              </main>
+            </div>
+          </div>
         </Flex>
       </Flex>
       <Footer config={config.footer} />
diff --git a/packages/chronicle/src/themes/default/Page.tsx b/packages/chronicle/src/themes/default/Page.tsx
index 247acf9..194cd67 100644
--- a/packages/chronicle/src/themes/default/Page.tsx
+++ b/packages/chronicle/src/themes/default/Page.tsx
@@ -1,16 +1,14 @@
 'use client';
 
 import { Flex } from '@raystack/apsara';
-import { Breadcrumbs } from '@/components/ui/breadcrumbs';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
 import { Toc } from './Toc';
 
-export function Page({ page, tree }: ThemePageProps) {
+export function Page({ page }: ThemePageProps) {
   return (
     <Flex className={styles.page}>
       <article className={styles.article} data-article-content>
-        <Breadcrumbs slug={page.slug} tree={tree} />
         <div className={styles.content}>{page.content}</div>
       </article>
       <Toc items={page.toc} />

From 6cd486f2f4aeda768d987d92e10840fed72beb09 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 16:14:04 +0530
Subject: [PATCH 7/9] feat: sidebar top navbar and layout polish

- Add sidebar top navbar with placeholder logo, icon-only search, and
  IconButton-based theme switcher using resolvedTheme so system mode
  lands on the correct icon.
- Simplify Search component to IconButton only, drop cmdk kbd trigger.
- Wrap content in a bordered card, remove TOC from Page, align heading
  + paragraph typography with Aurora tokens.
- Secondary bg on sidebar + card wrapper, primary bg on content area.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/ui/client-theme-switcher.tsx   | 25 ++++++++++--
 .../src/components/ui/search.module.css       | 13 -------
 .../chronicle/src/components/ui/search.tsx    | 38 ++++++-------------
 .../src/themes/default/Layout.module.css      | 38 +++++++++++++++++--
 .../chronicle/src/themes/default/Layout.tsx   | 18 ++++++++-
 .../src/themes/default/Page.module.css        | 30 +++++++++++++++
 .../chronicle/src/themes/default/Page.tsx     |  2 -
 7 files changed, 114 insertions(+), 50 deletions(-)

diff --git a/packages/chronicle/src/components/ui/client-theme-switcher.tsx b/packages/chronicle/src/components/ui/client-theme-switcher.tsx
index 34f9051..b504410 100644
--- a/packages/chronicle/src/components/ui/client-theme-switcher.tsx
+++ b/packages/chronicle/src/components/ui/client-theme-switcher.tsx
@@ -1,18 +1,35 @@
 'use client'
 
-import { ThemeSwitcher } from '@raystack/apsara'
-import { useState, useEffect } from 'react'
+import { MoonIcon, SunIcon } from '@heroicons/react/24/outline'
+import { IconButton, useTheme } from '@raystack/apsara'
+import { useEffect, useState } from 'react'
 
 interface ClientThemeSwitcherProps {
   size?: number
 }
 
-export function ClientThemeSwitcher({ size }: ClientThemeSwitcherProps) {
+export function ClientThemeSwitcher({ size = 16 }: ClientThemeSwitcherProps) {
   const [isClient, setIsClient] = useState(false)
+  const { resolvedTheme, setTheme } = useTheme()
 
   useEffect(() => {
     setIsClient(true)
   }, [])
 
-  return isClient ? <ThemeSwitcher size={size} /> : null
+  if (!isClient) return null
+
+  const isDark = resolvedTheme === 'dark'
+  return (
+    <IconButton
+      size={3}
+      aria-label={isDark ? 'Switch to light theme' : 'Switch to dark theme'}
+      onClick={() => setTheme(isDark ? 'light' : 'dark')}
+    >
+      {isDark ? (
+        <SunIcon width={size} height={size} />
+      ) : (
+        <MoonIcon width={size} height={size} />
+      )}
+    </IconButton>
+  )
 }
diff --git a/packages/chronicle/src/components/ui/search.module.css b/packages/chronicle/src/components/ui/search.module.css
index 086e7f4..6a6b4bf 100644
--- a/packages/chronicle/src/components/ui/search.module.css
+++ b/packages/chronicle/src/components/ui/search.module.css
@@ -1,16 +1,3 @@
-.trigger {
-  gap: 8px;
-  color: var(--rs-color-foreground-base-secondary);
-  cursor: pointer;
-}
-
-.kbd {
-  padding: 2px 6px;
-  border-radius: 4px;
-  border: 1px solid var(--rs-color-border-base-primary);
-  font-size: 12px;
-}
-
 .dialogContent {
   max-width: 600px;
   padding: 0;
diff --git a/packages/chronicle/src/components/ui/search.tsx b/packages/chronicle/src/components/ui/search.tsx
index 293893d..5517d17 100644
--- a/packages/chronicle/src/components/ui/search.tsx
+++ b/packages/chronicle/src/components/ui/search.tsx
@@ -1,6 +1,9 @@
-import { DocumentIcon, HashtagIcon } from '@heroicons/react/24/outline';
-import { Button, Command, Dialog, Text } from '@raystack/apsara';
-import { cx } from 'class-variance-authority';
+import {
+  DocumentIcon,
+  HashtagIcon,
+  MagnifyingGlassIcon
+} from '@heroicons/react/24/outline';
+import { Command, Dialog, IconButton, Text } from '@raystack/apsara';
 import type { SortedResult } from 'fumadocs-core/search';
 import { useDocsSearch } from 'fumadocs-core/search/client';
 import { useCallback, useEffect, useState } from 'react';
@@ -8,21 +11,6 @@ import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
 import styles from './search.module.css';
 
-function SearchShortcutKey({ className }: { className?: string }) {
-  const [key, setKey] = useState('⌘');
-
-  useEffect(() => {
-    const isMac = navigator.platform?.toUpperCase().includes('MAC');
-    setKey(isMac ? '⌘' : 'Ctrl');
-  }, []);
-
-  return (
-    <kbd className={className} suppressHydrationWarning>
-      {key} K
-    </kbd>
-  );
-}
-
 interface SearchProps {
   className?: string;
 }
@@ -64,16 +52,14 @@ export function Search({ className }: SearchProps) {
 
   return (
     <>
-      <Button
-        variant='outline'
-        color='neutral'
-        size='small'
+      <IconButton
+        size={3}
+        aria-label='Search'
         onClick={() => setOpen(true)}
-        className={cx(styles.trigger, className)}
-        trailingIcon={<SearchShortcutKey className={styles.kbd} />}
+        className={className}
       >
-        Search...
-      </Button>
+        <MagnifyingGlassIcon width={16} height={16} />
+      </IconButton>
 
       <Dialog open={open} onOpenChange={setOpen}>
         <Dialog.Content className={styles.dialogContent}>
diff --git a/packages/chronicle/src/themes/default/Layout.module.css b/packages/chronicle/src/themes/default/Layout.module.css
index afd2d2b..9028b42 100644
--- a/packages/chronicle/src/themes/default/Layout.module.css
+++ b/packages/chronicle/src/themes/default/Layout.module.css
@@ -11,6 +11,38 @@
   position: sticky;
   top: 0;
   height: 100vh;
+  background: var(--rs-color-background-base-secondary);
+}
+
+.sidebar[data-position='left'] {
+  border-right: none;
+  padding: 0;
+}
+
+.sidebarNavbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--rs-space-3);
+  width: 100%;
+  height: 48px;
+  padding: 0 var(--rs-space-5);
+  flex-shrink: 0;
+  backdrop-filter: blur(1px);
+}
+
+.sidebarNavLogo {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.sidebarNavActions {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-3);
+}
+
+.sidebarMain {
+  padding: var(--rs-space-7) var(--rs-space-5);
 }
 
 .mainArea {
@@ -24,7 +56,6 @@
   height: 48px;
   padding: 0 var(--rs-space-2);
   background: var(--rs-color-background-base-secondary);
-  border-bottom: 1px solid var(--rs-color-border-base-primary);
 }
 
 .tabs {
@@ -64,15 +95,15 @@
 .cardWrapper {
   flex: 1;
   display: flex;
-  padding: 0 var(--rs-space-2) var(--rs-space-2);
+  padding: 0 var(--rs-space-5) var(--rs-space-2) var(--rs-space-2);
   min-height: 0;
+  background: var(--rs-color-background-base-secondary);
 }
 
 .card {
   flex: 1;
   display: flex;
   flex-direction: column;
-  background: var(--rs-color-background-base-primary);
   border: 0.5px solid var(--rs-color-border-base-primary);
   border-radius: var(--rs-radius-4);
   box-shadow:
@@ -99,6 +130,7 @@
 .content {
   flex: 1;
   padding: var(--rs-space-9) var(--rs-space-7);
+  background: var(--rs-color-background-base-primary);
 }
 
 .groupItems {
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index d0d8cb9..4e28f6f 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -3,7 +3,8 @@ import {
   ArrowRightIcon,
   CodeBracketSquareIcon,
   DocumentTextIcon,
-  RectangleStackIcon
+  RectangleStackIcon,
+  Squares2X2Icon
 } from '@heroicons/react/24/outline';
 import { Flex, IconButton, Sidebar } from '@raystack/apsara';
 import { cx } from 'class-variance-authority';
@@ -11,7 +12,9 @@ import { useEffect, useMemo, useRef } from 'react';
 import { Link as RouterLink, useLocation, useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
 import { Breadcrumbs } from '@/components/ui/breadcrumbs';
+import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Footer } from '@/components/ui/footer';
+import { Search } from '@/components/ui/search';
 import { usePageContext } from '@/lib/page-context';
 import type { Node } from 'fumadocs-core/page-tree';
 import type { ThemeLayoutProps } from '@/types';
@@ -72,7 +75,18 @@ export function Layout({
           collapsible={false}
           className={cx(styles.sidebar, classNames?.sidebar)}
         >
-          <Sidebar.Main ref={scrollRef}>
+          <div className={styles.sidebarNavbar}>
+            <Squares2X2Icon
+              className={styles.sidebarNavLogo}
+              width={24}
+              height={24}
+            />
+            <div className={styles.sidebarNavActions}>
+              {config.search?.enabled && <Search />}
+              <ClientThemeSwitcher size={16} />
+            </div>
+          </div>
+          <Sidebar.Main ref={scrollRef} className={styles.sidebarMain}>
             {tree.children.map((item, i) => (
               <SidebarNode
                 key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
diff --git a/packages/chronicle/src/themes/default/Page.module.css b/packages/chronicle/src/themes/default/Page.module.css
index 40cb3f0..b019638 100644
--- a/packages/chronicle/src/themes/default/Page.module.css
+++ b/packages/chronicle/src/themes/default/Page.module.css
@@ -26,6 +26,36 @@
   line-height: 1.4;
 }
 
+.content > :is(h1, h2, h3, h4, h5, h6):first-child {
+  margin-top: 0;
+}
+
+.content h1 {
+  margin-top: 0;
+  margin-bottom: var(--rs-space-10);
+}
+
+.content p {
+  color: var(--rs-color-foreground-base-primary);
+  font-family: var(--rs-font-body);
+  font-size: var(--rs-font-size-regular);
+  font-style: normal;
+  font-weight: var(--rs-font-weight-regular);
+  line-height: 171.429%;
+}
+
+.content h2 {
+  margin-top: var(--rs-space-8);
+  margin-bottom: var(--rs-space-8);
+  color: var(--rs-color-foreground-base-primary);
+  font-family: var(--rs-font-title);
+  font-size: var(--rs-font-size-t3);
+  font-style: normal;
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-t3);
+  letter-spacing: var(--rs-letter-spacing-t3);
+}
+
 .content ul,
 .content ol {
   padding-left: var(--rs-space-5);
diff --git a/packages/chronicle/src/themes/default/Page.tsx b/packages/chronicle/src/themes/default/Page.tsx
index 194cd67..fa168ec 100644
--- a/packages/chronicle/src/themes/default/Page.tsx
+++ b/packages/chronicle/src/themes/default/Page.tsx
@@ -3,7 +3,6 @@
 import { Flex } from '@raystack/apsara';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
-import { Toc } from './Toc';
 
 export function Page({ page }: ThemePageProps) {
   return (
@@ -11,7 +10,6 @@ export function Page({ page }: ThemePageProps) {
       <article className={styles.article} data-article-content>
         <div className={styles.content}>{page.content}</div>
       </article>
-      <Toc items={page.toc} />
     </Flex>
   );
 }

From 29fa42dd7269019f6bed5dc095f76f2cf3bd70fc Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 16:44:26 +0530
Subject: [PATCH 8/9] feat: floating TOC with hover panel

TOC renders as short horizontal markers floating right-center, each
width scaled from the heading text length (base + per char, clamped).
Hovering the aside fades the markers out and reveals a panel with the
full heading list, active state highlighted. Shadows switch to the
Apsara --rs-shadow-soft token.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../src/themes/default/Layout.module.css      |   4 +-
 .../chronicle/src/themes/default/Page.tsx     |   2 +
 .../src/themes/default/Toc.module.css         | 121 ++++++++++++++----
 packages/chronicle/src/themes/default/Toc.tsx |  66 ++++++++--
 4 files changed, 154 insertions(+), 39 deletions(-)

diff --git a/packages/chronicle/src/themes/default/Layout.module.css b/packages/chronicle/src/themes/default/Layout.module.css
index 9028b42..f226f1a 100644
--- a/packages/chronicle/src/themes/default/Layout.module.css
+++ b/packages/chronicle/src/themes/default/Layout.module.css
@@ -106,9 +106,7 @@
   flex-direction: column;
   border: 0.5px solid var(--rs-color-border-base-primary);
   border-radius: var(--rs-radius-4);
-  box-shadow:
-    0 1px 2px 0 rgba(0, 0, 0, 0.04),
-    0 2px 4px 0 rgba(0, 0, 0, 0.04);
+  box-shadow: var(--rs-shadow-soft);
   overflow: clip;
 }
 
diff --git a/packages/chronicle/src/themes/default/Page.tsx b/packages/chronicle/src/themes/default/Page.tsx
index fa168ec..194cd67 100644
--- a/packages/chronicle/src/themes/default/Page.tsx
+++ b/packages/chronicle/src/themes/default/Page.tsx
@@ -3,6 +3,7 @@
 import { Flex } from '@raystack/apsara';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
+import { Toc } from './Toc';
 
 export function Page({ page }: ThemePageProps) {
   return (
@@ -10,6 +11,7 @@ export function Page({ page }: ThemePageProps) {
       <article className={styles.article} data-article-content>
         <div className={styles.content}>{page.content}</div>
       </article>
+      <Toc items={page.toc} />
     </Flex>
   );
 }
diff --git a/packages/chronicle/src/themes/default/Toc.module.css b/packages/chronicle/src/themes/default/Toc.module.css
index 16b8f24..48617ad 100644
--- a/packages/chronicle/src/themes/default/Toc.module.css
+++ b/packages/chronicle/src/themes/default/Toc.module.css
@@ -1,48 +1,117 @@
 .toc {
-  width: 200px;
-  flex-shrink: 0;
-  position: sticky;
-  top: var(--rs-space-9);
-  max-height: calc(100vh - var(--rs-space-17));
-  overflow-y: auto;
+  position: fixed;
+  right: calc(var(--rs-space-5) + var(--rs-space-3));
+  top: 50%;
+  transform: translateY(-50%);
+  z-index: 10;
 }
 
-.title {
+.markers {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--rs-space-4);
+  opacity: 1;
+  transition: opacity 150ms ease;
+}
+
+.toc:hover .markers {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.marker {
   display: block;
+  height: 2px;
+  background: var(--rs-color-border-base-secondary);
+  border-radius: 1px;
+  transition:
+    width 0.15s ease,
+    background 0.15s ease;
+}
+
+.marker:hover {
+  background: var(--rs-color-foreground-base-secondary);
+}
+
+.markerActive {
+  background: var(--rs-color-border-base-emphasis);
+}
+
+
+.panel {
+  position: absolute;
+  top: 50%;
+  right: 0;
+  transform: translateY(-50%) translateX(8px);
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-2);
+  min-width: 200px;
+  padding: var(--rs-space-3) 0;
+  background: var(--rs-color-background-base-primary);
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-4);
+  box-shadow: var(--rs-shadow-soft);
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease;
+}
+
+.toc:hover .panel {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateY(-50%) translateX(0);
+}
+
+.panelHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-3);
+  padding: var(--rs-space-3);
   color: var(--rs-color-foreground-base-secondary);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  margin-bottom: var(--rs-space-3);
-  font-size: var(--rs-font-size-mini);
+  font-family: var(--rs-font-body);
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
 }
 
-.nav {
+.panelHeaderLabel {
+  flex: 1;
+}
+
+.panelList {
   display: flex;
   flex-direction: column;
-  gap: 0;
-  border-left: 1px solid var(--rs-color-border-base-primary);
-  padding-left: var(--rs-space-3);
-  margin-bottom: var(--rs-space-6);
+  gap: var(--rs-space-1);
+  padding-left: var(--rs-space-8);
 }
 
-.link {
+.panelItem {
+  display: block;
+  padding: var(--rs-space-3);
+  border-radius: var(--rs-radius-2);
   color: var(--rs-color-foreground-base-tertiary);
-  text-decoration: none;
+  font-family: var(--rs-font-body);
   font-size: var(--rs-font-size-small);
-  line-height: 1.4;
-  padding: var(--rs-space-1) 0;
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  text-decoration: none;
   transition: color 0.15s ease;
 }
 
-.link:hover {
+.panelItem:hover {
   color: var(--rs-color-foreground-base-primary);
 }
 
-.active {
-  color: var(--rs-color-foreground-base-primary);
-  font-weight: 500;
+.panelItemNested {
+  padding-left: var(--rs-space-5);
 }
 
-.nested {
-  padding-left: var(--rs-space-3);
+.panelItemActive {
+  color: var(--rs-color-foreground-base-primary);
 }
diff --git a/packages/chronicle/src/themes/default/Toc.tsx b/packages/chronicle/src/themes/default/Toc.tsx
index 455befc..4a68a80 100644
--- a/packages/chronicle/src/themes/default/Toc.tsx
+++ b/packages/chronicle/src/themes/default/Toc.tsx
@@ -1,10 +1,23 @@
 'use client';
 
-import { Text } from '@raystack/apsara';
+import { Bars3BottomLeftIcon } from '@heroicons/react/24/outline';
 import { AnchorProvider, useActiveAnchor } from 'fumadocs-core/toc';
 import type { TableOfContents, TOCItemType } from 'fumadocs-core/toc';
+import { cx } from 'class-variance-authority';
+import { isValidElement, type ReactNode } from 'react';
 import styles from './Toc.module.css';
 
+function nodeToText(node: ReactNode): string {
+  if (node == null || typeof node === 'boolean') return '';
+  if (typeof node === 'string' || typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(nodeToText).join('');
+  if (isValidElement(node)) {
+    const children = (node.props as { children?: ReactNode }).children;
+    return nodeToText(children);
+  }
+  return '';
+}
+
 interface TocProps {
   items: TableOfContents;
 }
@@ -23,30 +36,63 @@ export function Toc({ items }: TocProps) {
   );
 }
 
+const MARKER_BASE = 8;
+const MARKER_PER_CHAR = 1;
+const MARKER_MAX = 40;
+
+function markerWidth(title: ReactNode): number {
+  const len = nodeToText(title).length;
+  return Math.min(MARKER_MAX, MARKER_BASE + len * MARKER_PER_CHAR);
+}
+
 function TocContent({ items }: { items: TOCItemType[] }) {
   const activeAnchor = useActiveAnchor();
 
   return (
-    <aside className={styles.toc}>
-      <Text size={1} weight='medium' className={styles.title}>
-        On this page
-      </Text>
-      <nav className={styles.nav}>
+    <aside className={styles.toc} aria-label='Table of contents'>
+      <div className={styles.markers}>
         {items.map(item => {
           const id = item.url.replace('#', '');
           const isActive = activeAnchor === id;
-          const isNested = item.depth > 2;
           return (
             <a
               key={item.url}
               href={item.url}
-              className={`${styles.link} ${isActive ? styles.active : ''} ${isNested ? styles.nested : ''}`}
+              aria-label={nodeToText(item.title)}
+              className={cx(styles.marker, isActive && styles.markerActive)}
+              style={{ width: `${markerWidth(item.title)}px` }}
             >
-              {item.title}
+              <span />
             </a>
           );
         })}
-      </nav>
+      </div>
+      <div className={styles.panel} role='presentation'>
+        <div className={styles.panelHeader}>
+          <Bars3BottomLeftIcon width={16} height={16} />
+          <span className={styles.panelHeaderLabel}>On this page</span>
+        </div>
+        <nav className={styles.panelList}>
+          {items.map(item => {
+            const id = item.url.replace('#', '');
+            const isActive = activeAnchor === id;
+            const isNested = item.depth > 2;
+            return (
+              <a
+                key={item.url}
+                href={item.url}
+                className={cx(
+                  styles.panelItem,
+                  isNested && styles.panelItemNested,
+                  isActive && styles.panelItemActive
+                )}
+              >
+                {nodeToText(item.title)}
+              </a>
+            );
+          })}
+        </nav>
+      </div>
     </aside>
   );
 }

From b634599a8d253db275b96a6b603262c6a14541a4 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 17 Apr 2026 16:47:27 +0530
Subject: [PATCH 9/9] fix: address PR review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- page-context: coerce prev/next from API response to null so the
  state always matches the Page type instead of carrying undefined.
- source.getPageNav: guard PageNavLink.title to string-only page names
  so ReactNode names don't stringify to "[object Object]".
- Layout tabs: compute per-entry active state from api.basePath instead
  of the shared isApiRoute boolean, so only the matching API tab
  highlights when multiple APIs are configured.
- Layout: skip breadcrumbs on API routes since the docs tree doesn't
  include API paths.
- Search: add title="Search (⌘K)" so the keyboard shortcut stays
  discoverable after the kbd hint was removed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/chronicle/src/components/ui/search.tsx  |  1 +
 packages/chronicle/src/lib/page-context.tsx      | 11 +++++++++--
 packages/chronicle/src/lib/source.ts             |  2 +-
 packages/chronicle/src/themes/default/Layout.tsx |  9 +++++++--
 4 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/packages/chronicle/src/components/ui/search.tsx b/packages/chronicle/src/components/ui/search.tsx
index 5517d17..086d61f 100644
--- a/packages/chronicle/src/components/ui/search.tsx
+++ b/packages/chronicle/src/components/ui/search.tsx
@@ -55,6 +55,7 @@ export function Search({ className }: SearchProps) {
       <IconButton
         size={3}
         aria-label='Search'
+        title='Search (⌘K)'
         onClick={() => setOpen(true)}
         className={className}
       >
diff --git a/packages/chronicle/src/lib/page-context.tsx b/packages/chronicle/src/lib/page-context.tsx
index b88de29..05ec253 100644
--- a/packages/chronicle/src/lib/page-context.tsx
+++ b/packages/chronicle/src/lib/page-context.tsx
@@ -105,12 +105,19 @@ export function PageProvider({
         }
         return res.json();
       })
-      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string; prev: Page['prev']; next: Page['next'] } | undefined) => {
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string; prev?: Page['prev']; next?: Page['next'] } | undefined) => {
         if (cancelled.current || !data) return;
         const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
         if (cancelled.current) return;
         setErrorStatus(null);
-        setPage({ slug, frontmatter: data.frontmatter, content, toc, prev: data.prev, next: data.next });
+        setPage({
+          slug,
+          frontmatter: data.frontmatter,
+          content,
+          toc,
+          prev: data.prev ?? null,
+          next: data.next ?? null
+        });
       })
       .catch(() => {
         if (!cancelled.current) {
diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts
index 2fd1e26..aa4da0a 100644
--- a/packages/chronicle/src/lib/source.ts
+++ b/packages/chronicle/src/lib/source.ts
@@ -114,7 +114,7 @@ export async function getPageNav(slug: string[]): Promise<PageNav> {
   if (i < 0) return { prev: null, next: null };
   const toLink = (p: (typeof pages)[number]): PageNavLink => ({
     url: p.url,
-    title: String(p.name ?? '')
+    title: typeof p.name === 'string' ? p.name : ''
   });
   return {
     prev: i > 0 ? toLink(pages[i - 1]) : null,
diff --git a/packages/chronicle/src/themes/default/Layout.tsx b/packages/chronicle/src/themes/default/Layout.tsx
index 4e28f6f..a32a6f2 100644
--- a/packages/chronicle/src/themes/default/Layout.tsx
+++ b/packages/chronicle/src/themes/default/Layout.tsx
@@ -42,6 +42,8 @@ export function Layout({
   const { page } = usePageContext();
   const scrollRef = useRef<HTMLDivElement>(null);
   const isApiRoute = pathname.startsWith('/apis');
+  const isApiBase = (basePath: string) =>
+    pathname === basePath || pathname.startsWith(`${basePath}/`);
   const { prev, next } = page ?? { prev: null, next: null };
 
   const slug = useMemo(
@@ -110,7 +112,10 @@ export function Layout({
                 <RouterLink
                   key={api.basePath}
                   to={api.basePath}
-                  className={cx(styles.tab, isApiRoute && styles.tabActive)}
+                  className={cx(
+                    styles.tab,
+                    isApiBase(api.basePath) && styles.tabActive
+                  )}
                 >
                   <CodeBracketSquareIcon width={12} height={12} />
                   <span>{api.name} API</span>
@@ -140,7 +145,7 @@ export function Layout({
                       <ArrowRightIcon width={14} height={14} />
                     </IconButton>
                   </Flex>
-                  <Breadcrumbs slug={slug} tree={tree} />
+                  {!isApiRoute && <Breadcrumbs slug={slug} tree={tree} />}
                 </Flex>
               </nav>
               <main className={cx(styles.content, classNames?.content)}>