From 4e2caa1e2e4797b50d26a4c67a44d51253e21c0c Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Thu, 19 Feb 2026 09:47:35 +0530
Subject: [PATCH 1/9] fix: resolve TypeScript build errors

Update tsconfig lib to ES2022 for error.cause support and fix invalid
IconButton props (size/variant) to match Apsara component types.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/chronicle/next-env.d.ts                           | 2 +-
 packages/chronicle/src/components/api/field-row.tsx        | 4 ++--
 packages/chronicle/src/components/api/key-value-editor.tsx | 2 +-
 packages/chronicle/tsconfig.json                           | 1 +
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/chronicle/next-env.d.ts b/packages/chronicle/next-env.d.ts
index c4b7818f..9edff1c7 100644
--- a/packages/chronicle/next-env.d.ts
+++ b/packages/chronicle/next-env.d.ts
@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/packages/chronicle/src/components/api/field-row.tsx b/packages/chronicle/src/components/api/field-row.tsx
index c7458dfe..1ede3ddc 100644
--- a/packages/chronicle/src/components/api/field-row.tsx
+++ b/packages/chronicle/src/components/api/field-row.tsx
@@ -63,7 +63,7 @@ export function FieldRow({ field, location, editable, value, onChange }: FieldRo
         <Flex direction="column" className={styles.main}>
           <Flex align="center" justify="between">
             {label}
-            <IconButton size="small" variant="ghost" onClick={() => {
+            <IconButton size={1} onClick={() => {
               const newItem = itemChildren ? {} : ''
               onChange?.(field.name, [...items, newItem])
             }}>
@@ -105,7 +105,7 @@ export function FieldRow({ field, location, editable, value, onChange }: FieldRo
                     }}
                   />
                 )}
-                <IconButton size="small" variant="ghost" onClick={() => {
+                <IconButton size={1} onClick={() => {
                   const updated = items.filter((_, j) => j !== i)
                   onChange?.(field.name, updated)
                 }}>
diff --git a/packages/chronicle/src/components/api/key-value-editor.tsx b/packages/chronicle/src/components/api/key-value-editor.tsx
index b2960897..ed8ce391 100644
--- a/packages/chronicle/src/components/api/key-value-editor.tsx
+++ b/packages/chronicle/src/components/api/key-value-editor.tsx
@@ -49,7 +49,7 @@ export function KeyValueEditor({ entries, onChange }: KeyValueEditorProps) {
               onChange={(e) => updateEntry(i, 'value', e.target.value)}
             />
           </div>
-          <IconButton size="small" variant="ghost" aria-label={`Delete ${entry.key || 'entry'}`} onClick={() => removeEntry(i)}>
+          <IconButton size={1} aria-label={`Delete ${entry.key || 'entry'}`} onClick={() => removeEntry(i)}>
             <TrashIcon width={14} height={14} />
           </IconButton>
         </Flex>
diff --git a/packages/chronicle/tsconfig.json b/packages/chronicle/tsconfig.json
index ecfaea9f..471ded2f 100644
--- a/packages/chronicle/tsconfig.json
+++ b/packages/chronicle/tsconfig.json
@@ -4,6 +4,7 @@
     "outDir": "dist",
     "rootDir": ".",
     "baseUrl": ".",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "moduleResolution": "bundler",
     "paths": {
       "@/*": ["./src/*"],

From 6981860a6989ed0d7a59e6551e54967aa8883fdc Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Thu, 19 Feb 2026 12:19:41 +0530
Subject: [PATCH 2/9] feat: add paper theme with dynamic theme registry

Add theme registry for config-driven theme selection and implement
paper theme with chapter nav, serif content, reading progress ruler,
and prev/next navigation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../chronicle/src/app/[[...slug]]/page.tsx    |  4 +-
 .../src/app/apis/[[...slug]]/layout.tsx       |  3 +-
 .../src/themes/paper/ChapterNav.module.css    | 58 ++++++++++++++++
 .../chronicle/src/themes/paper/ChapterNav.tsx | 69 +++++++++++++++++++
 .../src/themes/paper/Layout.module.css        | 33 +++++++++
 .../chronicle/src/themes/paper/Layout.tsx     | 36 ++++++++++
 .../src/themes/paper/Page.module.css          | 15 ++++
 packages/chronicle/src/themes/paper/Page.tsx  | 21 ++++++
 .../src/themes/paper/PrevNextNav.module.css   | 25 +++++++
 .../src/themes/paper/PrevNextNav.tsx          | 43 ++++++++++++
 .../themes/paper/ReadingProgress.module.css   | 47 +++++++++++++
 .../src/themes/paper/ReadingProgress.tsx      | 60 ++++++++++++++++
 packages/chronicle/src/themes/paper/index.ts  |  8 +++
 packages/chronicle/src/themes/registry.ts     | 14 ++++
 14 files changed, 433 insertions(+), 3 deletions(-)
 create mode 100644 packages/chronicle/src/themes/paper/ChapterNav.module.css
 create mode 100644 packages/chronicle/src/themes/paper/ChapterNav.tsx
 create mode 100644 packages/chronicle/src/themes/paper/Layout.module.css
 create mode 100644 packages/chronicle/src/themes/paper/Layout.tsx
 create mode 100644 packages/chronicle/src/themes/paper/Page.module.css
 create mode 100644 packages/chronicle/src/themes/paper/Page.tsx
 create mode 100644 packages/chronicle/src/themes/paper/PrevNextNav.module.css
 create mode 100644 packages/chronicle/src/themes/paper/PrevNextNav.tsx
 create mode 100644 packages/chronicle/src/themes/paper/ReadingProgress.module.css
 create mode 100644 packages/chronicle/src/themes/paper/ReadingProgress.tsx
 create mode 100644 packages/chronicle/src/themes/paper/index.ts
 create mode 100644 packages/chronicle/src/themes/registry.ts

diff --git a/packages/chronicle/src/app/[[...slug]]/page.tsx b/packages/chronicle/src/app/[[...slug]]/page.tsx
index 8231f34b..077fe87c 100644
--- a/packages/chronicle/src/app/[[...slug]]/page.tsx
+++ b/packages/chronicle/src/app/[[...slug]]/page.tsx
@@ -2,7 +2,7 @@ import { notFound } from 'next/navigation'
 import type { MDXContent } from 'mdx/types'
 import { loadConfig } from '../../lib/config'
 import { source, buildPageTree } from '../../lib/source'
-import { defaultTheme } from '../../themes/default'
+import { getTheme } from '../../themes/registry'
 import { mdxComponents } from '../../components/mdx'
 
 interface PageProps {
@@ -26,7 +26,7 @@ export default async function DocsPage({ params }: PageProps) {
     notFound()
   }
 
-  const { Layout, Page } = defaultTheme
+  const { Layout, Page } = getTheme(config.theme?.name)
 
   const data = page.data as PageData
   const MDXBody = data.body
diff --git a/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx b/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx
index b27b9c05..e9f03c76 100644
--- a/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx
+++ b/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx
@@ -1,11 +1,12 @@
 import { loadConfig } from '../../../lib/config'
 import { loadApiSpecs } from '../../../lib/openapi'
 import { buildApiPageTree } from '../../../lib/api-routes'
-import { Layout } from '../../../themes/default'
+import { getTheme } from '../../../themes/registry'
 import styles from './layout.module.css'
 
 export default function ApiLayout({ children }: { children: React.ReactNode }) {
   const config = loadConfig()
+  const { Layout } = getTheme(config.theme?.name)
   const specs = loadApiSpecs(config.api ?? [])
   const tree = buildApiPageTree(specs)
 
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.module.css b/packages/chronicle/src/themes/paper/ChapterNav.module.css
new file mode 100644
index 00000000..97acf63a
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/ChapterNav.module.css
@@ -0,0 +1,58 @@
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-5);
+}
+
+.chapter {
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-2);
+}
+
+.chapterLabel {
+  font-size: var(--rs-font-size-small);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.chapterItems {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--rs-space-1);
+  padding-left: var(--rs-space-4);
+}
+
+.item {
+  list-style: none;
+}
+
+.link {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-2);
+  font-size: var(--rs-font-size-small);
+  color: var(--rs-color-foreground-base-tertiary);
+  text-decoration: none;
+  padding: var(--rs-space-1) 0;
+}
+
+.link:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.active {
+  color: var(--rs-color-foreground-accent-primary);
+  font-weight: 500;
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.tsx b/packages/chronicle/src/themes/paper/ChapterNav.tsx
new file mode 100644
index 00000000..7c1e5735
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/ChapterNav.tsx
@@ -0,0 +1,69 @@
+'use client'
+
+import { usePathname } from 'next/navigation'
+import NextLink from 'next/link'
+import { MethodBadge } from '../../components/api/method-badge'
+import type { PageTree, PageTreeItem } from '../../types'
+import styles from './ChapterNav.module.css'
+
+const iconMap: Record<string, React.ReactNode> = {
+  'method-get': <MethodBadge method="GET" size="micro" />,
+  'method-post': <MethodBadge method="POST" size="micro" />,
+  'method-put': <MethodBadge method="PUT" size="micro" />,
+  'method-delete': <MethodBadge method="DELETE" size="micro" />,
+  'method-patch': <MethodBadge method="PATCH" size="micro" />,
+}
+
+interface ChapterNavProps {
+  tree: PageTree
+}
+
+export function ChapterNav({ tree }: ChapterNavProps) {
+  const pathname = usePathname()
+  let chapterIndex = 0
+
+  return (
+    <nav className={styles.nav}>
+      {tree.children.map((item) => {
+        if (item.type === 'separator') return null
+
+        if (item.type === 'folder' && item.children) {
+          chapterIndex++
+          return (
+            <div key={item.name} className={styles.chapter}>
+              <span className={styles.chapterLabel}>
+                {String(chapterIndex).padStart(2, '0')}. {item.name}
+              </span>
+              <ul className={styles.chapterItems}>
+                {item.children.map((child) => (
+                  <ChapterItem key={child.url ?? child.name} item={child} pathname={pathname} />
+                ))}
+              </ul>
+            </div>
+          )
+        }
+
+        return <ChapterItem key={item.url ?? item.name} item={item} pathname={pathname} />
+      })}
+    </nav>
+  )
+}
+
+function ChapterItem({ item, pathname }: { item: PageTreeItem; pathname: string }) {
+  if (item.type === 'separator') return null
+
+  const isActive = pathname === item.url
+  const icon = item.icon ? iconMap[item.icon] : null
+
+  return (
+    <li className={styles.item}>
+      <NextLink
+        href={item.url ?? '#'}
+        className={`${styles.link} ${isActive ? styles.active : ''}`}
+      >
+        {icon && <span className={styles.icon}>{icon}</span>}
+        <span>{item.name}</span>
+      </NextLink>
+    </li>
+  )
+}
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
new file mode 100644
index 00000000..e6124676
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -0,0 +1,33 @@
+.layout {
+  min-height: 100vh;
+}
+
+.header {
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+}
+
+.body {
+  flex: 1;
+}
+
+.sidebar {
+  width: 260px;
+  padding: var(--rs-space-7) var(--rs-space-5);
+  border-right: 1px solid var(--rs-color-border-base-primary);
+  overflow-y: auto;
+  font-family: 'SF Mono', 'Fira Code', 'Fira Mono', 'Roboto Mono', monospace;
+}
+
+.title {
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--rs-color-foreground-accent-primary);
+  font-family: inherit;
+  margin-bottom: var(--rs-space-7);
+}
+
+.content {
+  flex: 1;
+  padding: var(--rs-space-9);
+  overflow-y: auto;
+}
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
new file mode 100644
index 00000000..9b52bf1c
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -0,0 +1,36 @@
+'use client'
+
+import { Flex, Navbar, Headline } from '@raystack/apsara'
+import { ClientThemeSwitcher } from '../../components/ui/client-theme-switcher'
+import { Search } from '../../components/ui/search'
+import { Footer } from '../../components/ui/footer'
+import { ChapterNav } from './ChapterNav'
+import { PrevNextNav } from './PrevNextNav'
+import type { ThemeLayoutProps } from '../../types'
+import styles from './Layout.module.css'
+
+export function Layout({ children, config, tree }: ThemeLayoutProps) {
+  return (
+    <Flex direction="column" className={styles.layout}>
+      <Navbar className={styles.header}>
+        <Navbar.Start>
+          {config.search?.enabled && <Search />}
+        </Navbar.Start>
+        <Navbar.End>
+          <PrevNextNav tree={tree} />
+          <ClientThemeSwitcher size={16} />
+        </Navbar.End>
+      </Navbar>
+      <Flex className={styles.body}>
+        <aside className={styles.sidebar}>
+          <Headline size="small" weight="medium" as="h1" className={styles.title}>
+            {config.title}
+          </Headline>
+          <ChapterNav tree={tree} />
+        </aside>
+        <main className={styles.content}>{children}</main>
+      </Flex>
+      <Footer config={config.footer} />
+    </Flex>
+  )
+}
diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
new file mode 100644
index 00000000..6c996c0e
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -0,0 +1,15 @@
+.page {
+  gap: var(--rs-space-9);
+}
+
+.article {
+  flex: 1;
+  min-width: 0;
+  max-width: 720px;
+}
+
+.content {
+  font-family: Georgia, 'Times New Roman', serif;
+  line-height: 1.8;
+  margin-top: var(--rs-space-5);
+}
diff --git a/packages/chronicle/src/themes/paper/Page.tsx b/packages/chronicle/src/themes/paper/Page.tsx
new file mode 100644
index 00000000..86cf1592
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/Page.tsx
@@ -0,0 +1,21 @@
+'use client'
+
+import { Flex } from '@raystack/apsara'
+import type { ThemePageProps } from '../../types'
+import { Breadcrumbs } from '../../components/ui/breadcrumbs'
+import { ReadingProgress } from './ReadingProgress'
+import styles from './Page.module.css'
+
+export function Page({ page, tree }: ThemePageProps) {
+  return (
+    <Flex className={styles.page}>
+      <article className={styles.article}>
+        <Breadcrumbs slug={page.slug} tree={tree} />
+        <div className={styles.content}>
+          {page.content}
+        </div>
+      </article>
+      <ReadingProgress items={page.toc} />
+    </Flex>
+  )
+}
diff --git a/packages/chronicle/src/themes/paper/PrevNextNav.module.css b/packages/chronicle/src/themes/paper/PrevNextNav.module.css
new file mode 100644
index 00000000..f06d2e72
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/PrevNextNav.module.css
@@ -0,0 +1,25 @@
+.nav {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-3);
+}
+
+.arrow {
+  font-family: 'SF Mono', 'Fira Code', monospace;
+  font-size: var(--rs-font-size-base);
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+  padding: var(--rs-space-1) var(--rs-space-2);
+}
+
+.arrow:hover {
+  color: var(--rs-color-foreground-accent-primary);
+}
+
+.disabled {
+  font-family: 'SF Mono', 'Fira Code', monospace;
+  font-size: var(--rs-font-size-base);
+  color: var(--rs-color-foreground-base-tertiary);
+  padding: var(--rs-space-1) var(--rs-space-2);
+  opacity: 0.4;
+}
diff --git a/packages/chronicle/src/themes/paper/PrevNextNav.tsx b/packages/chronicle/src/themes/paper/PrevNextNav.tsx
new file mode 100644
index 00000000..696cd95a
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/PrevNextNav.tsx
@@ -0,0 +1,43 @@
+'use client'
+
+import { usePathname } from 'next/navigation'
+import NextLink from 'next/link'
+import type { PageTree, PageTreeItem } from '../../types'
+import styles from './PrevNextNav.module.css'
+
+function flattenTree(items: PageTreeItem[]): PageTreeItem[] {
+  const result: PageTreeItem[] = []
+  for (const item of items) {
+    if (item.type === 'page' && item.url) result.push(item)
+    if (item.children) result.push(...flattenTree(item.children))
+  }
+  return result
+}
+
+interface PrevNextNavProps {
+  tree: PageTree
+}
+
+export function PrevNextNav({ tree }: PrevNextNavProps) {
+  const pathname = usePathname()
+  const pages = flattenTree(tree.children)
+  const currentIndex = pages.findIndex((p) => p.url === pathname)
+
+  const prev = currentIndex > 0 ? pages[currentIndex - 1] : null
+  const next = currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null
+
+  return (
+    <nav className={styles.nav}>
+      {prev ? (
+        <NextLink href={prev.url!} className={styles.arrow}>{'<'}</NextLink>
+      ) : (
+        <span className={styles.disabled}>{'<'}</span>
+      )}
+      {next ? (
+        <NextLink href={next.url!} className={styles.arrow}>{'>'}</NextLink>
+      ) : (
+        <span className={styles.disabled}>{'>'}</span>
+      )}
+    </nav>
+  )
+}
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.module.css b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
new file mode 100644
index 00000000..82b6211b
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
@@ -0,0 +1,47 @@
+.ruler {
+  width: 200px;
+  flex-shrink: 0;
+  position: sticky;
+  top: var(--rs-space-9);
+  max-height: calc(100vh - var(--rs-space-17));
+  overflow-y: auto;
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  gap: var(--rs-space-3);
+}
+
+.mark {
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-2);
+  text-decoration: none;
+  color: var(--rs-color-foreground-base-tertiary);
+  transition: color 0.15s ease;
+}
+
+.mark:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.dash {
+  flex-shrink: 0;
+  font-family: 'SF Mono', 'Fira Code', monospace;
+}
+
+.label {
+  font-family: 'SF Mono', 'Fira Code', monospace;
+  font-size: var(--rs-font-size-mini);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.active {
+  color: var(--rs-color-foreground-accent-primary);
+}
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.tsx b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
new file mode 100644
index 00000000..102684db
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
@@ -0,0 +1,60 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import type { TocItem } from '../../types'
+import styles from './ReadingProgress.module.css'
+
+interface ReadingProgressProps {
+  items: TocItem[]
+}
+
+export function ReadingProgress({ items }: ReadingProgressProps) {
+  const [activeId, setActiveId] = useState<string>('')
+
+  const h2Items = items.filter((item) => item.depth === 2)
+
+  useEffect(() => {
+    const headingIds = h2Items.map((item) => item.url.replace('#', ''))
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id)
+          }
+        })
+      },
+      { rootMargin: '-80px 0px -80% 0px' }
+    )
+
+    headingIds.forEach((id) => {
+      const element = document.getElementById(id)
+      if (element) observer.observe(element)
+    })
+
+    return () => observer.disconnect()
+  }, [h2Items])
+
+  if (h2Items.length === 0) return null
+
+  return (
+    <aside className={styles.ruler}>
+      <nav className={styles.nav}>
+        {h2Items.map((item) => {
+          const id = item.url.replace('#', '')
+          const isActive = activeId === id
+          return (
+            <a
+              key={item.url}
+              href={item.url}
+              className={`${styles.mark} ${isActive ? styles.active : ''}`}
+            >
+              <span className={styles.dash}>—</span>
+              <span className={styles.label}>{item.title}</span>
+            </a>
+          )
+        })}
+      </nav>
+    </aside>
+  )
+}
diff --git a/packages/chronicle/src/themes/paper/index.ts b/packages/chronicle/src/themes/paper/index.ts
new file mode 100644
index 00000000..103c7c78
--- /dev/null
+++ b/packages/chronicle/src/themes/paper/index.ts
@@ -0,0 +1,8 @@
+import { Layout } from './Layout'
+import { Page } from './Page'
+import type { Theme } from '../../types'
+
+export const paperTheme: Theme = {
+  Layout,
+  Page,
+}
diff --git a/packages/chronicle/src/themes/registry.ts b/packages/chronicle/src/themes/registry.ts
new file mode 100644
index 00000000..bba8e8c3
--- /dev/null
+++ b/packages/chronicle/src/themes/registry.ts
@@ -0,0 +1,14 @@
+import type { Theme } from '../types'
+import { defaultTheme } from './default'
+import { paperTheme } from './paper'
+
+const themes: Record<string, Theme> = {
+  default: defaultTheme,
+  paper: paperTheme,
+}
+
+export function getTheme(name?: string): Theme {
+  if (!name || !themes[name]) return defaultTheme
+
+  return themes[name]
+}

From 0b430164899226d6ebcd2cae826bf40ecc07c62e Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Thu, 19 Feb 2026 15:00:15 +0530
Subject: [PATCH 3/9] feat: refine paper theme layout, navbar, and page styling

Restructure paper layout with sticky navbar (arrows + breadcrumb + search),
paper-style content area with shadow/borders, neutral background,
and full-height reading progress ruler. Remove PrevNextNav component,
add className prop to Search.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../chronicle/src/components/ui/search.tsx    |  9 +-
 .../src/themes/paper/Layout.module.css        |  8 +-
 .../chronicle/src/themes/paper/Layout.tsx     | 14 +--
 .../src/themes/paper/Page.module.css          | 93 +++++++++++++++++-
 packages/chronicle/src/themes/paper/Page.tsx  | 98 +++++++++++++++++--
 .../src/themes/paper/PrevNextNav.module.css   | 25 -----
 .../src/themes/paper/PrevNextNav.tsx          | 43 --------
 .../themes/paper/ReadingProgress.module.css   |  6 +-
 8 files changed, 192 insertions(+), 104 deletions(-)
 delete mode 100644 packages/chronicle/src/themes/paper/PrevNextNav.module.css
 delete mode 100644 packages/chronicle/src/themes/paper/PrevNextNav.tsx

diff --git a/packages/chronicle/src/components/ui/search.tsx b/packages/chronicle/src/components/ui/search.tsx
index 0f910be0..21f1ef43 100644
--- a/packages/chronicle/src/components/ui/search.tsx
+++ b/packages/chronicle/src/components/ui/search.tsx
@@ -3,6 +3,7 @@
 import { useState, useEffect, useCallback } from "react";
 import { useRouter } from "next/navigation";
 import { Button, Command, Dialog, Text } from "@raystack/apsara";
+import { cx } from "class-variance-authority";
 import { useDocsSearch } from "fumadocs-core/search/client";
 import type { SortedResult } from "fumadocs-core/search";
 import { DocumentIcon, HashtagIcon } from "@heroicons/react/24/outline";
@@ -24,7 +25,11 @@ function SearchShortcutKey({ className }: { className?: string }) {
   );
 }
 
-export function Search() {
+interface SearchProps {
+  className?: string
+}
+
+export function Search({ className }: SearchProps) {
   const [open, setOpen] = useState(false);
   const router = useRouter();
 
@@ -65,7 +70,7 @@ export function Search() {
         variant="outline"
         color="neutral"
         onClick={() => setOpen(true)}
-        className={styles.trigger}
+        className={cx(styles.trigger, className)}
         trailingIcon={<SearchShortcutKey className={styles.kbd} />}
       >
         <Text>Search...</Text>
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index e6124676..c98fb526 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -2,10 +2,6 @@
   min-height: 100vh;
 }
 
-.header {
-  border-bottom: 1px solid var(--rs-color-border-base-primary);
-}
-
 .body {
   flex: 1;
 }
@@ -13,7 +9,7 @@
 .sidebar {
   width: 260px;
   padding: var(--rs-space-7) var(--rs-space-5);
-  border-right: 1px solid var(--rs-color-border-base-primary);
+  background: var(--rs-color-background-neutral-primary);
   overflow-y: auto;
   font-family: 'SF Mono', 'Fira Code', 'Fira Mono', 'Roboto Mono', monospace;
 }
@@ -23,11 +19,11 @@
   letter-spacing: 0.08em;
   color: var(--rs-color-foreground-accent-primary);
   font-family: inherit;
+  font-size: var(--rs-font-size-mono-large);
   margin-bottom: var(--rs-space-7);
 }
 
 .content {
   flex: 1;
-  padding: var(--rs-space-9);
   overflow-y: auto;
 }
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
index 9b52bf1c..b9a1f568 100644
--- a/packages/chronicle/src/themes/paper/Layout.tsx
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -1,26 +1,14 @@
 'use client'
 
-import { Flex, Navbar, Headline } from '@raystack/apsara'
-import { ClientThemeSwitcher } from '../../components/ui/client-theme-switcher'
-import { Search } from '../../components/ui/search'
+import { Flex, Headline } from '@raystack/apsara'
 import { Footer } from '../../components/ui/footer'
 import { ChapterNav } from './ChapterNav'
-import { PrevNextNav } from './PrevNextNav'
 import type { ThemeLayoutProps } from '../../types'
 import styles from './Layout.module.css'
 
 export function Layout({ children, config, tree }: ThemeLayoutProps) {
   return (
     <Flex direction="column" className={styles.layout}>
-      <Navbar className={styles.header}>
-        <Navbar.Start>
-          {config.search?.enabled && <Search />}
-        </Navbar.Start>
-        <Navbar.End>
-          <PrevNextNav tree={tree} />
-          <ClientThemeSwitcher size={16} />
-        </Navbar.End>
-      </Navbar>
       <Flex className={styles.body}>
         <aside className={styles.sidebar}>
           <Headline size="small" weight="medium" as="h1" className={styles.title}>
diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
index 6c996c0e..0854c9f5 100644
--- a/packages/chronicle/src/themes/paper/Page.module.css
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -1,15 +1,102 @@
 .page {
-  gap: var(--rs-space-9);
+  height: 100%;
+  overflow-y: auto;
+  background: var(--rs-color-background-neutral-primary);
+}
+
+.main {
+  flex: 1;
+  max-width: 1024px;
+  margin: 0 auto;
+}
+
+.navbar {
+  padding: var(--rs-space-1) 0;
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+  flex-shrink: 0;
+  justify-content: space-between;
+  width: 100%;
+  position: sticky;
+  top: 0;
+  background: var(--rs-color-background-neutral-primary);
+  z-index: 10;
+}
+
+.navLeft {
+  align-items: center;
+}
+
+.navRight {
+  align-items: center;
+}
+
+.arrow {
+  display: flex;
+  align-items: center;
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+}
+
+.arrow:hover {
+  color: var(--rs-color-foreground-accent-primary);
+}
+
+.arrowDisabled {
+  display: flex;
+  align-items: center;
+  color: var(--rs-color-foreground-base-tertiary);
+  opacity: 0.4;
+}
+
+.breadcrumb {
+  font-family: 'SF Mono', 'Fira Code', monospace;
+  font-size: var(--rs-font-size-small);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-left: var(--rs-space-3);
+}
+
+.separator {
+  margin: 0 var(--rs-space-2);
+  color: var(--rs-color-foreground-base-tertiary);
+}
+
+.crumbLink {
+  color: var(--rs-color-foreground-base-tertiary);
+  text-decoration: none;
+}
+
+.crumbLink:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.crumbActive {
+  color: var(--rs-color-foreground-base-primary);
+  font-weight: 600;
 }
 
 .article {
   flex: 1;
   min-width: 0;
-  max-width: 720px;
+  margin-top: var(--rs-space-7);
+  padding: 0 var(--rs-space-7);
+}
+
+.searchButton {
+  height: 28px;
+  padding: 0 var(--rs-space-3);
+  font-size: var(--rs-font-size-small);
+  border: none;
+  box-shadow: none;
 }
 
 .content {
   font-family: Georgia, 'Times New Roman', serif;
   line-height: 1.8;
-  margin-top: var(--rs-space-5);
+  background: var(--rs-color-background-base-primary);
+  padding: var(--rs-space-9);
+  border-left: 1px solid var(--rs-color-border-base-primary);
+  border-right: 1px solid var(--rs-color-border-base-primary);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 4px 12px rgba(0, 0, 0, 0.04);
+  margin-bottom: var(--rs-space-9);
 }
diff --git a/packages/chronicle/src/themes/paper/Page.tsx b/packages/chronicle/src/themes/paper/Page.tsx
index 86cf1592..0bfb4937 100644
--- a/packages/chronicle/src/themes/paper/Page.tsx
+++ b/packages/chronicle/src/themes/paper/Page.tsx
@@ -1,20 +1,100 @@
 'use client'
 
+import { usePathname } from 'next/navigation'
+import NextLink from 'next/link'
 import { Flex } from '@raystack/apsara'
-import type { ThemePageProps } from '../../types'
-import { Breadcrumbs } from '../../components/ui/breadcrumbs'
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline'
+import type { ThemePageProps, PageTreeItem } from '../../types'
+import { Search } from '../../components/ui/search'
 import { ReadingProgress } from './ReadingProgress'
 import styles from './Page.module.css'
 
-export function Page({ page, tree }: ThemePageProps) {
+function flattenTree(items: PageTreeItem[]): PageTreeItem[] {
+  const result: PageTreeItem[] = []
+  for (const item of items) {
+    if (item.type === 'page' && item.url) result.push(item)
+    if (item.children) result.push(...flattenTree(item.children))
+  }
+  return result
+}
+
+function findBreadcrumb(items: PageTreeItem[], slug: string[]): { label: string; href: string }[] {
+  const result: { label: string; href: string }[] = []
+  for (let i = 0; i < slug.length; i++) {
+    const path = '/' + slug.slice(0, i + 1).join('/')
+    const found = findInTree(items, path)
+    result.push({ label: found?.name ?? slug[i], href: path })
+  }
+  return result
+}
+
+function findInTree(items: PageTreeItem[], path: string): PageTreeItem | undefined {
+  for (const item of items) {
+    if (item.url === path) return item
+    if (item.children) {
+      const found = findInTree(item.children, path)
+      if (found) return found
+    }
+  }
+  return undefined
+}
+
+export function Page({ page, config, tree }: ThemePageProps) {
+  const pathname = usePathname()
+  const pages = flattenTree(tree.children)
+  const currentIndex = pages.findIndex((p) => p.url === pathname)
+  const prev = currentIndex > 0 ? pages[currentIndex - 1] : null
+  const next = currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null
+  const crumbs = findBreadcrumb(tree.children, page.slug)
+
   return (
     <Flex className={styles.page}>
-      <article className={styles.article}>
-        <Breadcrumbs slug={page.slug} tree={tree} />
-        <div className={styles.content}>
-          {page.content}
-        </div>
-      </article>
+      <Flex direction="column" className={styles.main}>
+        <Flex align="center" className={styles.navbar}>
+          <Flex align="center" gap="small" className={styles.navLeft}>
+            {prev ? (
+              <NextLink href={prev.url!} className={styles.arrow}>
+                <ChevronLeftIcon width={14} height={14} />
+              </NextLink>
+            ) : (
+              <span className={styles.arrowDisabled}>
+                <ChevronLeftIcon width={14} height={14} />
+              </span>
+            )}
+            {next ? (
+              <NextLink href={next.url!} className={styles.arrow}>
+                <ChevronRightIcon width={14} height={14} />
+              </NextLink>
+            ) : (
+              <span className={styles.arrowDisabled}>
+                <ChevronRightIcon width={14} height={14} />
+              </span>
+            )}
+            <nav className={styles.breadcrumb}>
+              {crumbs.map((crumb, i) => (
+                <span key={crumb.href}>
+                  {i > 0 && <span className={styles.separator}>/</span>}
+                  {i === crumbs.length - 1 ? (
+                    <span className={styles.crumbActive}>{crumb.label}</span>
+                  ) : (
+                    <NextLink href={crumb.href} className={styles.crumbLink}>
+                      {crumb.label}
+                    </NextLink>
+                  )}
+                </span>
+              ))}
+            </nav>
+          </Flex>
+          <Flex align="center" className={styles.navRight}>
+            {config.search?.enabled && <Search className={styles.searchButton} />}
+          </Flex>
+        </Flex>
+        <article className={styles.article}>
+          <div className={styles.content}>
+            {page.content}
+          </div>
+        </article>
+      </Flex>
       <ReadingProgress items={page.toc} />
     </Flex>
   )
diff --git a/packages/chronicle/src/themes/paper/PrevNextNav.module.css b/packages/chronicle/src/themes/paper/PrevNextNav.module.css
deleted file mode 100644
index f06d2e72..00000000
--- a/packages/chronicle/src/themes/paper/PrevNextNav.module.css
+++ /dev/null
@@ -1,25 +0,0 @@
-.nav {
-  display: flex;
-  align-items: center;
-  gap: var(--rs-space-3);
-}
-
-.arrow {
-  font-family: 'SF Mono', 'Fira Code', monospace;
-  font-size: var(--rs-font-size-base);
-  color: var(--rs-color-foreground-base-primary);
-  text-decoration: none;
-  padding: var(--rs-space-1) var(--rs-space-2);
-}
-
-.arrow:hover {
-  color: var(--rs-color-foreground-accent-primary);
-}
-
-.disabled {
-  font-family: 'SF Mono', 'Fira Code', monospace;
-  font-size: var(--rs-font-size-base);
-  color: var(--rs-color-foreground-base-tertiary);
-  padding: var(--rs-space-1) var(--rs-space-2);
-  opacity: 0.4;
-}
diff --git a/packages/chronicle/src/themes/paper/PrevNextNav.tsx b/packages/chronicle/src/themes/paper/PrevNextNav.tsx
deleted file mode 100644
index 696cd95a..00000000
--- a/packages/chronicle/src/themes/paper/PrevNextNav.tsx
+++ /dev/null
@@ -1,43 +0,0 @@
-'use client'
-
-import { usePathname } from 'next/navigation'
-import NextLink from 'next/link'
-import type { PageTree, PageTreeItem } from '../../types'
-import styles from './PrevNextNav.module.css'
-
-function flattenTree(items: PageTreeItem[]): PageTreeItem[] {
-  const result: PageTreeItem[] = []
-  for (const item of items) {
-    if (item.type === 'page' && item.url) result.push(item)
-    if (item.children) result.push(...flattenTree(item.children))
-  }
-  return result
-}
-
-interface PrevNextNavProps {
-  tree: PageTree
-}
-
-export function PrevNextNav({ tree }: PrevNextNavProps) {
-  const pathname = usePathname()
-  const pages = flattenTree(tree.children)
-  const currentIndex = pages.findIndex((p) => p.url === pathname)
-
-  const prev = currentIndex > 0 ? pages[currentIndex - 1] : null
-  const next = currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null
-
-  return (
-    <nav className={styles.nav}>
-      {prev ? (
-        <NextLink href={prev.url!} className={styles.arrow}>{'<'}</NextLink>
-      ) : (
-        <span className={styles.disabled}>{'<'}</span>
-      )}
-      {next ? (
-        <NextLink href={next.url!} className={styles.arrow}>{'>'}</NextLink>
-      ) : (
-        <span className={styles.disabled}>{'>'}</span>
-      )}
-    </nav>
-  )
-}
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.module.css b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
index 82b6211b..779a5702 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.module.css
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
@@ -2,9 +2,9 @@
   width: 200px;
   flex-shrink: 0;
   position: sticky;
-  top: var(--rs-space-9);
-  max-height: calc(100vh - var(--rs-space-17));
-  overflow-y: auto;
+  top: 0;
+  height: 100%;
+  padding-top: 100px;
 }
 
 .nav {

From 27fc7e6b264edb599aa46afd7cece4659cc6e372 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Thu, 19 Feb 2026 15:22:19 +0530
Subject: [PATCH 4/9] fix: fixed navbar, fixed reading progress, paper-style
 content

Navbar and ReadingProgress use position fixed. Layout content
is the scroll container with scrollbar at browser edge. Neutral
background on sidebar and content area.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../chronicle/src/themes/paper/Layout.module.css  |  2 ++
 packages/chronicle/src/themes/paper/Layout.tsx    |  2 +-
 .../chronicle/src/themes/paper/Page.module.css    | 15 +++++----------
 packages/chronicle/src/themes/paper/Page.tsx      |  8 ++++----
 .../src/themes/paper/ReadingProgress.module.css   |  8 +++-----
 5 files changed, 15 insertions(+), 20 deletions(-)

diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index c98fb526..a8066167 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -26,4 +26,6 @@
 .content {
   flex: 1;
   overflow-y: auto;
+  background: var(--rs-color-background-neutral-primary);
+  padding-right: 260px;
 }
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
index b9a1f568..dc2ca2c0 100644
--- a/packages/chronicle/src/themes/paper/Layout.tsx
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -16,7 +16,7 @@ export function Layout({ children, config, tree }: ThemeLayoutProps) {
           </Headline>
           <ChapterNav tree={tree} />
         </aside>
-        <main className={styles.content}>{children}</main>
+        <div className={styles.content}>{children}</div>
       </Flex>
       <Footer config={config.footer} />
     </Flex>
diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
index 0854c9f5..bb49a539 100644
--- a/packages/chronicle/src/themes/paper/Page.module.css
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -1,9 +1,3 @@
-.page {
-  height: 100%;
-  overflow-y: auto;
-  background: var(--rs-color-background-neutral-primary);
-}
-
 .main {
   flex: 1;
   max-width: 1024px;
@@ -11,15 +5,16 @@
 }
 
 .navbar {
-  padding: var(--rs-space-1) 0;
+  height: 40px;
+  padding: var(--rs-space-3) 0;
   border-bottom: 1px solid var(--rs-color-border-base-primary);
-  flex-shrink: 0;
   justify-content: space-between;
   width: 100%;
-  position: sticky;
+  position: fixed;
   top: 0;
   background: var(--rs-color-background-neutral-primary);
   z-index: 10;
+  max-width: 1024px;
 }
 
 .navLeft {
@@ -78,7 +73,7 @@
 .article {
   flex: 1;
   min-width: 0;
-  margin-top: var(--rs-space-7);
+  margin-top: 72px;
   padding: 0 var(--rs-space-7);
 }
 
diff --git a/packages/chronicle/src/themes/paper/Page.tsx b/packages/chronicle/src/themes/paper/Page.tsx
index 0bfb4937..976aab38 100644
--- a/packages/chronicle/src/themes/paper/Page.tsx
+++ b/packages/chronicle/src/themes/paper/Page.tsx
@@ -48,8 +48,8 @@ export function Page({ page, config, tree }: ThemePageProps) {
   const crumbs = findBreadcrumb(tree.children, page.slug)
 
   return (
-    <Flex className={styles.page}>
-      <Flex direction="column" className={styles.main}>
+    <>
+      <main className={styles.main}>
         <Flex align="center" className={styles.navbar}>
           <Flex align="center" gap="small" className={styles.navLeft}>
             {prev ? (
@@ -94,8 +94,8 @@ export function Page({ page, config, tree }: ThemePageProps) {
             {page.content}
           </div>
         </article>
-      </Flex>
+      </main>
       <ReadingProgress items={page.toc} />
-    </Flex>
+    </>
   )
 }
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.module.css b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
index 779a5702..ca9c42cb 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.module.css
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
@@ -1,10 +1,8 @@
 .ruler {
   width: 200px;
-  flex-shrink: 0;
-  position: sticky;
-  top: 0;
-  height: 100%;
-  padding-top: 100px;
+  position: fixed;
+  right: 0;
+  top: 100px;
 }
 
 .nav {

From c393b7b5fa2597d47482b9d234345124b45224c6 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Thu, 19 Feb 2026 16:15:55 +0530
Subject: [PATCH 5/9] feat: rewrite ReadingProgress as tick-based ruler TOC

Replaces simple heading list with Apsara-style ruler TOC featuring
tick marks, scroll marker with percentage, heading labels on hover,
and connecting lines. Monospace font, fixed positioning.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/chronicle/src/themes/paper/Page.tsx  |   2 +-
 .../themes/paper/ReadingProgress.module.css   | 141 +++++++--
 .../src/themes/paper/ReadingProgress.tsx      | 291 +++++++++++++++---
 3 files changed, 368 insertions(+), 66 deletions(-)

diff --git a/packages/chronicle/src/themes/paper/Page.tsx b/packages/chronicle/src/themes/paper/Page.tsx
index 976aab38..04b52d36 100644
--- a/packages/chronicle/src/themes/paper/Page.tsx
+++ b/packages/chronicle/src/themes/paper/Page.tsx
@@ -89,7 +89,7 @@ export function Page({ page, config, tree }: ThemePageProps) {
             {config.search?.enabled && <Search className={styles.searchButton} />}
           </Flex>
         </Flex>
-        <article className={styles.article}>
+        <article className={styles.article} data-article-content>
           <div className={styles.content}>
             {page.content}
           </div>
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.module.css b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
index ca9c42cb..afc1e646 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.module.css
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
@@ -1,45 +1,132 @@
-.ruler {
-  width: 200px;
+.container {
   position: fixed;
-  right: 0;
+  right: var(--rs-space-4);
   top: 100px;
+  width: 200px;
+  height: calc(100vh - 200px);
+  z-index: 10;
 }
 
-.nav {
-  display: flex;
-  flex-direction: column;
-  justify-content: space-between;
-  gap: var(--rs-space-3);
+.inner {
+  position: absolute;
+  inset: 0;
 }
 
-.mark {
-  display: flex;
+.tickContainer {
+  position: absolute;
+  right: 0;
+  display: grid;
+  width: 6rem;
   align-items: center;
-  gap: var(--rs-space-2);
-  text-decoration: none;
-  color: var(--rs-color-foreground-base-tertiary);
-  transition: color 0.15s ease;
+  justify-content: flex-end;
 }
 
-.mark:hover {
-  color: var(--rs-color-foreground-base-primary);
+.tickLine {
+  height: 1px;
+  width: 0.5rem;
+  transition: all 100ms;
 }
 
-.dash {
-  flex-shrink: 0;
-  font-family: 'SF Mono', 'Fira Code', monospace;
+.tickLineBefore {
+  background-color: var(--rs-color-background-neutral-tertiary);
+}
+
+.tickLineAfter {
+  background-color: var(--rs-color-background-neutral-tertiary);
+}
+
+.tickContainer:hover .tickLine {
+  width: 1rem;
+}
+
+.tickClickable {
+  position: absolute;
+  inset-inline: 0;
+  height: 0.5rem;
+  cursor: pointer;
+}
+
+.headingContainer {
+  transition: transform 150ms;
+}
+
+.headingContainer:hover {
+  transform: translateX(-0.125rem);
+}
+
+.headingLabel {
+  position: absolute;
+  display: flex;
+  height: 0.75rem;
+  align-items: center;
+  font-family: var(--rs-font-mono);
+  font-size: 0.75rem;
+  color: var(--rs-color-foreground-base-primary);
+  text-transform: capitalize;
+  opacity: 0;
+  transition: opacity 300ms;
 }
 
-.label {
+.headingLink {
+  color: var(--rs-color-foreground-base-primary);
+  text-align: right;
   font-family: 'SF Mono', 'Fira Code', monospace;
   font-size: var(--rs-font-size-mini);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+  font-weight: var(--rs-font-weight-regular);
+  line-height: var(--rs-line-height-mini);
+  letter-spacing: var(--rs-letter-spacing-mini);
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.headingLink:hover {
+  color: var(--rs-color-cobalt-600, #0066cc);
+}
+
+.container:hover .headingLabel {
+  opacity: 1;
+}
+
+.connectingLine {
+  position: absolute;
+  right: 0;
+  height: 1px;
+  background-color: var(--rs-color-background-neutral-emphasis);
+}
+
+.scrollMarkerContainer {
+  position: absolute;
+  right: 0;
+  z-index: 20;
+  transition: opacity 300ms;
+  pointer-events: none;
+}
+
+.scrollMarkerContainerReady {
+  opacity: 1;
+}
+
+.scrollMarkerContainerNotReady {
+  opacity: 0;
+}
+
+.scrollMarkerLine {
+  height: 1px;
+  width: 1rem;
+  background-color: var(--rs-color-cobalt-600, #0066cc);
+}
+
+.scrollMarkerText {
+  position: absolute;
+  top: 0;
+  left: -2.5rem;
+  transform: translateY(-50%);
+  font-family: var(--rs-font-mono);
+  font-size: 0.75rem;
+  color: var(--rs-color-cobalt-600, #0066cc);
+  transition: opacity 300ms;
 }
 
-.active {
-  color: var(--rs-color-foreground-accent-primary);
+.container:hover .scrollMarkerText {
+  opacity: 0;
 }
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.tsx b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
index 102684db..71b3bb55 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.tsx
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
@@ -1,60 +1,275 @@
 'use client'
 
-import { useEffect, useState } from 'react'
+import { cx } from 'class-variance-authority'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { TocItem } from '../../types'
 import styles from './ReadingProgress.module.css'
 
+interface Heading {
+  title: string
+  level: number
+  id: string
+  url: string
+  yPosition: number
+}
+
+const ARTICLE_SELECTOR = '[data-article-content]'
+const TICK_HEIGHT = 20
+const NAV_HEIGHT = 60
+
+function calculateTickBounds(containerHeight: number) {
+  const numTicks = Math.floor(containerHeight / TICK_HEIGHT) + 1
+  const maxPosition = (numTicks - 1) * TICK_HEIGHT
+  return { numTicks, maxPosition }
+}
+
+function snapToTick(value: number, maxPosition: number): number {
+  const snapped = Math.round(value / TICK_HEIGHT) * TICK_HEIGHT
+  return Math.max(0, Math.min(snapped, maxPosition))
+}
+
+function resolveOverlaps(headings: Heading[], maxPosition: number): Heading[] {
+  if (headings.length <= 1) return headings
+
+  const resolved: Heading[] = []
+  let lastUsedPos = -TICK_HEIGHT
+
+  for (const heading of headings) {
+    let newPos = heading.yPosition
+    if (newPos <= lastUsedPos) {
+      newPos = lastUsedPos + TICK_HEIGHT
+    }
+    resolved.push({ ...heading, yPosition: newPos })
+    lastUsedPos = newPos
+  }
+
+  for (let i = resolved.length - 1; i >= 0; i--) {
+    const maxAllowed =
+      i === resolved.length - 1
+        ? maxPosition
+        : resolved[i + 1].yPosition - TICK_HEIGHT
+
+    if (resolved[i].yPosition > maxAllowed) {
+      resolved[i] = { ...resolved[i], yPosition: Math.max(0, maxAllowed) }
+    }
+  }
+
+  return resolved
+}
+
 interface ReadingProgressProps {
   items: TocItem[]
 }
 
 export function ReadingProgress({ items }: ReadingProgressProps) {
-  const [activeId, setActiveId] = useState<string>('')
+  const [headings, setHeadings] = useState<Heading[]>([])
+  const [containerHeight, setContainerHeight] = useState<number>(0)
+  const [ready, setReady] = useState<boolean>(false)
+  const [isScrollable, setIsScrollable] = useState<boolean>(true)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const scrollMarkerRef = useRef<HTMLDivElement>(null)
+  const scrollPosRef = useRef<number>(0)
+
+  const { numTicks, maxPosition } = useMemo(
+    () => calculateTickBounds(containerHeight),
+    [containerHeight]
+  )
+
+  const recalcHeadings = useCallback(() => {
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    const container = containerRef.current
+    if (!article || !container || !items.length) return
+
+    const articleBox = article.getBoundingClientRect()
+    const containerBox = container.getBoundingClientRect()
+    const articleTop = articleBox.top + window.scrollY
+
+    const hasScroll = articleBox.height > window.innerHeight
+    setIsScrollable(hasScroll)
+    setContainerHeight(containerBox.height)
 
-  const h2Items = items.filter((item) => item.depth === 2)
+    const { maxPosition: maxPos } = calculateTickBounds(containerBox.height)
+
+    const mapped = items
+      .map((tocItem) => {
+        const id = tocItem.url.startsWith('#') ? tocItem.url.slice(1) : tocItem.url
+        const node = document.getElementById(id)
+        if (!node) return null
+
+        const { top } = node.getBoundingClientRect()
+        const headingPosInArticle = top + window.scrollY - articleTop
+        const progress = headingPosInArticle / articleBox.height
+        const rawY = progress * maxPos
+        const yPos = snapToTick(rawY, maxPos)
+
+        return {
+          title: tocItem.title,
+          level: tocItem.depth,
+          id,
+          url: tocItem.url,
+          yPosition: yPos,
+        }
+      })
+      .filter((item): item is Heading => item !== null)
+
+    const resolvedItems = resolveOverlaps(mapped, maxPos)
+    setHeadings(resolvedItems)
+  }, [items])
+
+  const handleScroll = useCallback(() => {
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    const container = containerRef.current
+    const scrollMarker = scrollMarkerRef.current
+    if (!article || !container || !scrollMarker) return
+
+    const { top, height } = article.getBoundingClientRect()
+    const { height: cHeight } = container.getBoundingClientRect()
+    const viewportHeight = window.innerHeight
+    const { maxPosition: maxPos } = calculateTickBounds(cHeight)
+
+    let newScrollPos: number
+    if (top > 0) {
+      newScrollPos = 0
+    } else {
+      const scrolled = Math.abs(top)
+      const scrollRange = height - viewportHeight
+      const progress = scrollRange > 0 ? Math.min(1, scrolled / scrollRange) : 0
+      const rawPos = progress * maxPos
+      newScrollPos = snapToTick(rawPos, maxPos)
+    }
+
+    const prevScrollPos = scrollPosRef.current
+    if (newScrollPos !== prevScrollPos) {
+      scrollPosRef.current = newScrollPos
+      scrollMarker.style.top = `${newScrollPos}px`
+
+      const textEl = scrollMarker.querySelector('[data-scroll-text]')
+      if (textEl) {
+        textEl.textContent = (maxPos > 0 ? newScrollPos / maxPos : 0).toFixed(2)
+      }
+
+      const tickLines = container.querySelectorAll('[data-tick-line]')
+      tickLines.forEach((tick) => {
+        const tickPos = Number(tick.getAttribute('data-tick-pos'))
+        if (tickPos < newScrollPos) {
+          tick.classList.remove(styles.tickLineAfter)
+          tick.classList.add(styles.tickLineBefore)
+        } else {
+          tick.classList.remove(styles.tickLineBefore)
+          tick.classList.add(styles.tickLineAfter)
+        }
+      })
+    }
+  }, [])
 
   useEffect(() => {
-    const headingIds = h2Items.map((item) => item.url.replace('#', ''))
+    const init = setTimeout(() => {
+      recalcHeadings()
+      handleScroll()
+      setReady(true)
+    }, 250)
 
-    const observer = new IntersectionObserver(
-      (entries) => {
-        entries.forEach((entry) => {
-          if (entry.isIntersecting) {
-            setActiveId(entry.target.id)
-          }
-        })
-      },
-      { rootMargin: '-80px 0px -80% 0px' }
-    )
+    window.addEventListener('resize', recalcHeadings)
+    window.addEventListener('scroll', handleScroll, { passive: true })
 
-    headingIds.forEach((id) => {
-      const element = document.getElementById(id)
-      if (element) observer.observe(element)
-    })
+    return () => {
+      clearTimeout(init)
+      window.removeEventListener('resize', recalcHeadings)
+      window.removeEventListener('scroll', handleScroll)
+    }
+  }, [recalcHeadings, handleScroll])
 
-    return () => observer.disconnect()
-  }, [h2Items])
+  const scrollToTick = (y: number): void => {
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    if (!article || maxPosition === 0) return
 
-  if (h2Items.length === 0) return null
+    const articleBox = article.getBoundingClientRect()
+    const articleTop = articleBox.top + window.scrollY
+    const progress = y / maxPosition
+    const articlePos = progress * articleBox.height
+    const targetScroll = articleTop + articlePos - NAV_HEIGHT
+
+    window.scrollTo({ top: Math.max(0, targetScroll), behavior: 'smooth' })
+  }
+
+  const scrollToHeading = (id: string): void => {
+    const element = document.getElementById(id)
+    if (!element) return
+
+    const elementTop = element.getBoundingClientRect().top + window.scrollY
+    window.scrollTo({ top: Math.max(0, elementTop - NAV_HEIGHT), behavior: 'smooth' })
+  }
+
+  const ticks = useMemo(
+    () => Array.from({ length: numTicks }, (_, i) => i * TICK_HEIGHT),
+    [numTicks]
+  )
+
+  if (!isScrollable || ticks.length < 2) {
+    return <div ref={containerRef} className={styles.container} />
+  }
 
   return (
-    <aside className={styles.ruler}>
-      <nav className={styles.nav}>
-        {h2Items.map((item) => {
-          const id = item.url.replace('#', '')
-          const isActive = activeId === id
-          return (
-            <a
-              key={item.url}
-              href={item.url}
-              className={`${styles.mark} ${isActive ? styles.active : ''}`}
+    <div ref={containerRef} className={styles.container}>
+      <div className={styles.inner}>
+        {ticks.map((y, i) => (
+          <div key={`tick-${i}`} style={{ top: `${y}px` }} className={styles.tickContainer}>
+            <div data-tick-line data-tick-pos={y} className={cx(styles.tickLine, styles.tickLineAfter)} />
+            <div className={styles.tickClickable} onClick={() => scrollToTick(y)} />
+          </div>
+        ))}
+
+        {headings.map((h, i) => (
+          <div key={h.id || i} className={styles.headingContainer}>
+            <div
+              className={styles.headingLabel}
+              style={{
+                top: `${h.yPosition - 6}px`,
+                right: '24px',
+                zIndex: 10 * (h.level < 4 ? 1 : 0),
+                transitionDelay: `${50 * i}ms`,
+              }}
             >
-              <span className={styles.dash}>—</span>
-              <span className={styles.label}>{item.title}</span>
-            </a>
-          )
-        })}
-      </nav>
-    </aside>
+              <a
+                href={h.url}
+                className={styles.headingLink}
+                onClick={(e) => {
+                  e.preventDefault()
+                  e.stopPropagation()
+                  scrollToHeading(h.id)
+                }}
+              >
+                {h.title}
+              </a>
+            </div>
+          </div>
+        ))}
+
+        {headings.map((h, i) => (
+          <div
+            key={`line-${i}`}
+            className={styles.connectingLine}
+            style={{
+              top: `${h.yPosition}px`,
+              width: `${(3 - h.level) * 4 + 12}px`,
+            }}
+          />
+        ))}
+
+        <div
+          ref={scrollMarkerRef}
+          className={cx(
+            styles.scrollMarkerContainer,
+            ready ? styles.scrollMarkerContainerReady : styles.scrollMarkerContainerNotReady
+          )}
+          style={{ top: '0px' }}
+        >
+          <div className={styles.scrollMarkerLine} />
+          <span data-scroll-text className={styles.scrollMarkerText}>
+            0.00
+          </span>
+        </div>
+      </div>
+    </div>
   )
 }

From ee06184c00404d642d43181c7d1b4c96c91d6799 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Thu, 19 Feb 2026 16:18:03 +0530
Subject: [PATCH 6/9] feat: add prose typography styles to paper theme content

Add heading margins/sizes, paragraph spacing, list indentation,
and blockquote styling for proper content readability.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../src/themes/paper/Page.module.css          | 45 +++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
index bb49a539..24741a71 100644
--- a/packages/chronicle/src/themes/paper/Page.module.css
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -95,3 +95,48 @@
   box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 4px 12px rgba(0, 0, 0, 0.04);
   margin-bottom: var(--rs-space-9);
 }
+
+.content h1 {
+  margin: 2rem 0 1rem;
+  font-size: 2rem;
+}
+
+.content h2 {
+  margin: 1.75rem 0 0.75rem;
+  font-size: 1.5rem;
+}
+
+.content h3 {
+  margin: 1.5rem 0 0.5rem;
+  font-size: 1.25rem;
+}
+
+.content h4 {
+  margin: 1.25rem 0 0.5rem;
+  font-size: 1.1rem;
+}
+
+.content h5,
+.content h6 {
+  margin: 1rem 0 0.5rem;
+}
+
+.content p {
+  margin: 0.75rem 0;
+}
+
+.content ul,
+.content ol {
+  margin: 0.75rem 0;
+  padding-left: 1.5rem;
+}
+
+.content li {
+  margin: 0.25rem 0;
+}
+
+.content blockquote {
+  margin: 1rem 0;
+  padding-left: 1rem;
+  border-left: 3px solid var(--rs-color-border-base-primary);
+}

From 4af953071fa6a2b3c5198c4f60545bf64c78d727 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 20 Feb 2026 09:42:49 +0530
Subject: [PATCH 7/9] feat: support classNames in paper Layout, fix API sidebar
 and search

- Paper Layout supports classNames prop for overrides
- ChapterNav handles nested folders recursively for API endpoints
- Truncate sidebar text with ellipsis
- Hidden Search in API layout for Cmd+K support
- API layout removes right padding

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../src/app/apis/[[...slug]]/layout.module.css  |  5 +++++
 .../src/app/apis/[[...slug]]/layout.tsx         |  2 ++
 .../src/themes/paper/ChapterNav.module.css      | 17 +++++++++++++++++
 .../chronicle/src/themes/paper/ChapterNav.tsx   | 13 +++++++++++++
 packages/chronicle/src/themes/paper/Layout.tsx  | 11 ++++++-----
 5 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/packages/chronicle/src/app/apis/[[...slug]]/layout.module.css b/packages/chronicle/src/app/apis/[[...slug]]/layout.module.css
index 6e1094e7..a3c8ffe0 100644
--- a/packages/chronicle/src/app/apis/[[...slug]]/layout.module.css
+++ b/packages/chronicle/src/app/apis/[[...slug]]/layout.module.css
@@ -14,4 +14,9 @@
 .content {
   height: 100%;
   overflow-y: auto;
+  padding-right: 0;
+}
+
+.hiddenSearch {
+  display: none;
 }
diff --git a/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx b/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx
index e9f03c76..75a514d3 100644
--- a/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx
+++ b/packages/chronicle/src/app/apis/[[...slug]]/layout.tsx
@@ -2,6 +2,7 @@ import { loadConfig } from '../../../lib/config'
 import { loadApiSpecs } from '../../../lib/openapi'
 import { buildApiPageTree } from '../../../lib/api-routes'
 import { getTheme } from '../../../themes/registry'
+import { Search } from '../../../components/ui/search'
 import styles from './layout.module.css'
 
 export default function ApiLayout({ children }: { children: React.ReactNode }) {
@@ -17,6 +18,7 @@ export default function ApiLayout({ children }: { children: React.ReactNode }) {
       sidebar: styles.sidebar,
       content: styles.content,
     }}>
+      <Search className={styles.hiddenSearch} />
       {children}
     </Layout>
   )
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.module.css b/packages/chronicle/src/themes/paper/ChapterNav.module.css
index 97acf63a..2bc53082 100644
--- a/packages/chronicle/src/themes/paper/ChapterNav.module.css
+++ b/packages/chronicle/src/themes/paper/ChapterNav.module.css
@@ -16,6 +16,9 @@
   text-transform: uppercase;
   letter-spacing: 0.05em;
   color: var(--rs-color-foreground-base-primary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 .chapterItems {
@@ -40,6 +43,9 @@
   color: var(--rs-color-foreground-base-tertiary);
   text-decoration: none;
   padding: var(--rs-space-1) 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 .link:hover {
@@ -56,3 +62,14 @@
   align-items: center;
   flex-shrink: 0;
 }
+
+.subLabel {
+  font-size: var(--rs-font-size-small);
+  font-weight: 500;
+  color: var(--rs-color-foreground-base-secondary);
+  margin-top: var(--rs-space-3);
+  display: block;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.tsx b/packages/chronicle/src/themes/paper/ChapterNav.tsx
index 7c1e5735..78241463 100644
--- a/packages/chronicle/src/themes/paper/ChapterNav.tsx
+++ b/packages/chronicle/src/themes/paper/ChapterNav.tsx
@@ -52,6 +52,19 @@ export function ChapterNav({ tree }: ChapterNavProps) {
 function ChapterItem({ item, pathname }: { item: PageTreeItem; pathname: string }) {
   if (item.type === 'separator') return null
 
+  if (item.type === 'folder' && item.children) {
+    return (
+      <li className={styles.item}>
+        <span className={styles.subLabel}>{item.name}</span>
+        <ul className={styles.chapterItems}>
+          {item.children.map((child) => (
+            <ChapterItem key={child.url ?? child.name} item={child} pathname={pathname} />
+          ))}
+        </ul>
+      </li>
+    )
+  }
+
   const isActive = pathname === item.url
   const icon = item.icon ? iconMap[item.icon] : null
 
diff --git a/packages/chronicle/src/themes/paper/Layout.tsx b/packages/chronicle/src/themes/paper/Layout.tsx
index dc2ca2c0..488af76c 100644
--- a/packages/chronicle/src/themes/paper/Layout.tsx
+++ b/packages/chronicle/src/themes/paper/Layout.tsx
@@ -1,22 +1,23 @@
 'use client'
 
 import { Flex, Headline } from '@raystack/apsara'
+import { cx } from 'class-variance-authority'
 import { Footer } from '../../components/ui/footer'
 import { ChapterNav } from './ChapterNav'
 import type { ThemeLayoutProps } from '../../types'
 import styles from './Layout.module.css'
 
-export function Layout({ children, config, tree }: ThemeLayoutProps) {
+export function Layout({ children, config, tree, classNames }: ThemeLayoutProps) {
   return (
-    <Flex direction="column" className={styles.layout}>
-      <Flex className={styles.body}>
-        <aside className={styles.sidebar}>
+    <Flex direction="column" className={cx(styles.layout, classNames?.layout)}>
+      <Flex className={cx(styles.body, classNames?.body)}>
+        <aside className={cx(styles.sidebar, classNames?.sidebar)}>
           <Headline size="small" weight="medium" as="h1" className={styles.title}>
             {config.title}
           </Headline>
           <ChapterNav tree={tree} />
         </aside>
-        <div className={styles.content}>{children}</div>
+        <div className={cx(styles.content, classNames?.content)}>{children}</div>
       </Flex>
       <Footer config={config.footer} />
     </Flex>

From fe0af49d840334c7a3a2a9d8e051fca05875137c Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 20 Feb 2026 10:04:12 +0530
Subject: [PATCH 8/9] fix: address PR review issues for paper theme

- Add next-env.d.ts to .gitignore and remove from tracking
- Fix invalid HTML: wrap ChapterNav items in <ul>, precompute chapter indices
- Use CSS variables for sidebar width and navbar height (no magic numbers)
- Add explicit font-size for h5/h6 in prose styles
- Use semantic accent token for ReadingProgress tick/marker colors
- Use var(--rs-font-mono) consistently in ReadingProgress
- Replace setTimeout init with ResizeObserver for reliable layout detection
- Add Math.max guard for connecting line width at deep heading levels
- Add useMemo for derived navigation data in Page
- Use <button disabled> with aria-label for disabled prev/next arrows
- Remove redundant .item { list-style: none } in ChapterNav

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .gitignore                                    |  1 +
 packages/chronicle/next-env.d.ts              |  6 --
 .../src/themes/paper/ChapterNav.module.css    |  4 --
 .../chronicle/src/themes/paper/ChapterNav.tsx | 58 ++++++++++++-------
 .../src/themes/paper/Layout.module.css        |  5 +-
 .../src/themes/paper/Page.module.css          | 20 +++++--
 packages/chronicle/src/themes/paper/Page.tsx  | 28 +++++----
 .../themes/paper/ReadingProgress.module.css   | 10 ++--
 .../src/themes/paper/ReadingProgress.tsx      | 23 +++++---
 9 files changed, 94 insertions(+), 61 deletions(-)
 delete mode 100644 packages/chronicle/next-env.d.ts

diff --git a/.gitignore b/.gitignore
index 19e7f26e..63754daf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -86,6 +86,7 @@ web_modules/
 # Next.js build output
 .next
 out
+next-env.d.ts
 
 # Fumadocs generated
 .source
diff --git a/packages/chronicle/next-env.d.ts b/packages/chronicle/next-env.d.ts
deleted file mode 100644
index 9edff1c7..00000000
--- a/packages/chronicle/next-env.d.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.module.css b/packages/chronicle/src/themes/paper/ChapterNav.module.css
index 2bc53082..a7abaeb0 100644
--- a/packages/chronicle/src/themes/paper/ChapterNav.module.css
+++ b/packages/chronicle/src/themes/paper/ChapterNav.module.css
@@ -31,10 +31,6 @@
   padding-left: var(--rs-space-4);
 }
 
-.item {
-  list-style: none;
-}
-
 .link {
   display: flex;
   align-items: center;
diff --git a/packages/chronicle/src/themes/paper/ChapterNav.tsx b/packages/chronicle/src/themes/paper/ChapterNav.tsx
index 78241463..4c03c65f 100644
--- a/packages/chronicle/src/themes/paper/ChapterNav.tsx
+++ b/packages/chronicle/src/themes/paper/ChapterNav.tsx
@@ -18,33 +18,47 @@ interface ChapterNavProps {
   tree: PageTree
 }
 
+function buildChapterIndices(children: PageTreeItem[]): Map<PageTreeItem, number> {
+  const indices = new Map<PageTreeItem, number>()
+  let index = 0
+  for (const item of children) {
+    if (item.type === 'folder' && item.children) {
+      index++
+      indices.set(item, index)
+    }
+  }
+  return indices
+}
+
 export function ChapterNav({ tree }: ChapterNavProps) {
   const pathname = usePathname()
-  let chapterIndex = 0
+  const chapterIndices = buildChapterIndices(tree.children)
 
   return (
     <nav className={styles.nav}>
-      {tree.children.map((item) => {
-        if (item.type === 'separator') return null
+      <ul className={styles.chapterItems}>
+        {tree.children.map((item) => {
+          if (item.type === 'separator') return null
 
-        if (item.type === 'folder' && item.children) {
-          chapterIndex++
-          return (
-            <div key={item.name} className={styles.chapter}>
-              <span className={styles.chapterLabel}>
-                {String(chapterIndex).padStart(2, '0')}. {item.name}
-              </span>
-              <ul className={styles.chapterItems}>
-                {item.children.map((child) => (
-                  <ChapterItem key={child.url ?? child.name} item={child} pathname={pathname} />
-                ))}
-              </ul>
-            </div>
-          )
-        }
+          if (item.type === 'folder' && item.children) {
+            const chapterIndex = chapterIndices.get(item) ?? 0
+            return (
+              <li key={item.name} className={styles.chapter}>
+                <span className={styles.chapterLabel}>
+                  {String(chapterIndex).padStart(2, '0')}. {item.name}
+                </span>
+                <ul className={styles.chapterItems}>
+                  {item.children.map((child) => (
+                    <ChapterItem key={child.url ?? child.name} item={child} pathname={pathname} />
+                  ))}
+                </ul>
+              </li>
+            )
+          }
 
-        return <ChapterItem key={item.url ?? item.name} item={item} pathname={pathname} />
-      })}
+          return <ChapterItem key={item.url ?? item.name} item={item} pathname={pathname} />
+        })}
+      </ul>
     </nav>
   )
 }
@@ -54,7 +68,7 @@ function ChapterItem({ item, pathname }: { item: PageTreeItem; pathname: string
 
   if (item.type === 'folder' && item.children) {
     return (
-      <li className={styles.item}>
+      <li>
         <span className={styles.subLabel}>{item.name}</span>
         <ul className={styles.chapterItems}>
           {item.children.map((child) => (
@@ -69,7 +83,7 @@ function ChapterItem({ item, pathname }: { item: PageTreeItem; pathname: string
   const icon = item.icon ? iconMap[item.icon] : null
 
   return (
-    <li className={styles.item}>
+    <li>
       <NextLink
         href={item.url ?? '#'}
         className={`${styles.link} ${isActive ? styles.active : ''}`}
diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index a8066167..0634eef9 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -1,4 +1,5 @@
 .layout {
+  --paper-sidebar-width: 260px;
   min-height: 100vh;
 }
 
@@ -7,7 +8,7 @@
 }
 
 .sidebar {
-  width: 260px;
+  width: var(--paper-sidebar-width);
   padding: var(--rs-space-7) var(--rs-space-5);
   background: var(--rs-color-background-neutral-primary);
   overflow-y: auto;
@@ -27,5 +28,5 @@
   flex: 1;
   overflow-y: auto;
   background: var(--rs-color-background-neutral-primary);
-  padding-right: 260px;
+  padding-right: var(--paper-sidebar-width);
 }
diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
index 24741a71..a3d27f9f 100644
--- a/packages/chronicle/src/themes/paper/Page.module.css
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -1,12 +1,15 @@
 .main {
+  --paper-navbar-height: 40px;
+  --paper-navbar-padding: var(--rs-space-3);
+  --paper-navbar-total: calc(var(--paper-navbar-height) + var(--paper-navbar-padding) * 2 + 1px);
   flex: 1;
   max-width: 1024px;
   margin: 0 auto;
 }
 
 .navbar {
-  height: 40px;
-  padding: var(--rs-space-3) 0;
+  height: var(--paper-navbar-height);
+  padding: var(--paper-navbar-padding) 0;
   border-bottom: 1px solid var(--rs-color-border-base-primary);
   justify-content: space-between;
   width: 100%;
@@ -41,6 +44,10 @@
   align-items: center;
   color: var(--rs-color-foreground-base-tertiary);
   opacity: 0.4;
+  cursor: default;
+  border: none;
+  background: none;
+  padding: 0;
 }
 
 .breadcrumb {
@@ -73,7 +80,7 @@
 .article {
   flex: 1;
   min-width: 0;
-  margin-top: 72px;
+  margin-top: var(--paper-navbar-total);
   padding: 0 var(--rs-space-7);
 }
 
@@ -116,9 +123,14 @@
   font-size: 1.1rem;
 }
 
-.content h5,
+.content h5 {
+  margin: 1rem 0 0.5rem;
+  font-size: 1rem;
+}
+
 .content h6 {
   margin: 1rem 0 0.5rem;
+  font-size: 0.875rem;
 }
 
 .content p {
diff --git a/packages/chronicle/src/themes/paper/Page.tsx b/packages/chronicle/src/themes/paper/Page.tsx
index 04b52d36..72ff9112 100644
--- a/packages/chronicle/src/themes/paper/Page.tsx
+++ b/packages/chronicle/src/themes/paper/Page.tsx
@@ -1,5 +1,6 @@
 'use client'
 
+import { useMemo } from 'react'
 import { usePathname } from 'next/navigation'
 import NextLink from 'next/link'
 import { Flex } from '@raystack/apsara'
@@ -41,11 +42,16 @@ function findInTree(items: PageTreeItem[], path: string): PageTreeItem | undefin
 
 export function Page({ page, config, tree }: ThemePageProps) {
   const pathname = usePathname()
-  const pages = flattenTree(tree.children)
-  const currentIndex = pages.findIndex((p) => p.url === pathname)
-  const prev = currentIndex > 0 ? pages[currentIndex - 1] : null
-  const next = currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null
-  const crumbs = findBreadcrumb(tree.children, page.slug)
+
+  const { prev, next, crumbs } = useMemo(() => {
+    const pages = flattenTree(tree.children)
+    const currentIndex = pages.findIndex((p) => p.url === pathname)
+    return {
+      prev: currentIndex > 0 ? pages[currentIndex - 1] : null,
+      next: currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null,
+      crumbs: findBreadcrumb(tree.children, page.slug),
+    }
+  }, [tree, pathname, page.slug])
 
   return (
     <>
@@ -53,22 +59,22 @@ export function Page({ page, config, tree }: ThemePageProps) {
         <Flex align="center" className={styles.navbar}>
           <Flex align="center" gap="small" className={styles.navLeft}>
             {prev ? (
-              <NextLink href={prev.url!} className={styles.arrow}>
+              <NextLink href={prev.url!} className={styles.arrow} aria-label="Previous page">
                 <ChevronLeftIcon width={14} height={14} />
               </NextLink>
             ) : (
-              <span className={styles.arrowDisabled}>
+              <button disabled className={styles.arrowDisabled} aria-label="Previous page">
                 <ChevronLeftIcon width={14} height={14} />
-              </span>
+              </button>
             )}
             {next ? (
-              <NextLink href={next.url!} className={styles.arrow}>
+              <NextLink href={next.url!} className={styles.arrow} aria-label="Next page">
                 <ChevronRightIcon width={14} height={14} />
               </NextLink>
             ) : (
-              <span className={styles.arrowDisabled}>
+              <button disabled className={styles.arrowDisabled} aria-label="Next page">
                 <ChevronRightIcon width={14} height={14} />
-              </span>
+              </button>
             )}
             <nav className={styles.breadcrumb}>
               {crumbs.map((crumb, i) => (
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.module.css b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
index afc1e646..675060da 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.module.css
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.module.css
@@ -28,7 +28,7 @@
 }
 
 .tickLineBefore {
-  background-color: var(--rs-color-background-neutral-tertiary);
+  background-color: var(--rs-color-foreground-accent-primary);
 }
 
 .tickLineAfter {
@@ -70,7 +70,7 @@
 .headingLink {
   color: var(--rs-color-foreground-base-primary);
   text-align: right;
-  font-family: 'SF Mono', 'Fira Code', monospace;
+  font-family: var(--rs-font-mono);
   font-size: var(--rs-font-size-mini);
   font-weight: var(--rs-font-weight-regular);
   line-height: var(--rs-line-height-mini);
@@ -80,7 +80,7 @@
 }
 
 .headingLink:hover {
-  color: var(--rs-color-cobalt-600, #0066cc);
+  color: var(--rs-color-foreground-accent-primary);
 }
 
 .container:hover .headingLabel {
@@ -113,7 +113,7 @@
 .scrollMarkerLine {
   height: 1px;
   width: 1rem;
-  background-color: var(--rs-color-cobalt-600, #0066cc);
+  background-color: var(--rs-color-foreground-accent-primary);
 }
 
 .scrollMarkerText {
@@ -123,7 +123,7 @@
   transform: translateY(-50%);
   font-family: var(--rs-font-mono);
   font-size: 0.75rem;
-  color: var(--rs-color-cobalt-600, #0066cc);
+  color: var(--rs-color-foreground-accent-primary);
   transition: opacity 300ms;
 }
 
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.tsx b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
index 71b3bb55..a2625000 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.tsx
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
@@ -116,6 +116,7 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
     setHeadings(resolvedItems)
   }, [items])
 
+  // Imperative DOM updates to avoid React re-render on every scroll event
   const handleScroll = useCallback(() => {
     const article = document.querySelector(ARTICLE_SELECTOR)
     const container = containerRef.current
@@ -163,17 +164,25 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
   }, [])
 
   useEffect(() => {
-    const init = setTimeout(() => {
-      recalcHeadings()
-      handleScroll()
-      setReady(true)
-    }, 250)
+    recalcHeadings()
+    handleScroll()
+    setReady(true)
+
+    const article = document.querySelector(ARTICLE_SELECTOR)
+    let ro: ResizeObserver | undefined
+    if (article) {
+      ro = new ResizeObserver(() => {
+        recalcHeadings()
+        handleScroll()
+      })
+      ro.observe(article)
+    }
 
     window.addEventListener('resize', recalcHeadings)
     window.addEventListener('scroll', handleScroll, { passive: true })
 
     return () => {
-      clearTimeout(init)
+      ro?.disconnect()
       window.removeEventListener('resize', recalcHeadings)
       window.removeEventListener('scroll', handleScroll)
     }
@@ -251,7 +260,7 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
             className={styles.connectingLine}
             style={{
               top: `${h.yPosition}px`,
-              width: `${(3 - h.level) * 4 + 12}px`,
+              width: `${Math.max(4, (3 - h.level) * 4 + 12)}px`,
             }}
           />
         ))}

From f94569f8b89e374d8fdd58c2a51cee3b69f10044 Mon Sep 17 00:00:00 2001
From: Rishabh <me@rsbh.dev>
Date: Fri, 20 Feb 2026 11:18:15 +0530
Subject: [PATCH 9/9] fix: resolve overlapping headings and stylelint issues

- Fix resolveOverlaps backward pass to propagate clamp-and-shift,
  preventing multiple headings from collapsing to same position
- Add blank line after CSS custom properties (stylelint)
- Simplify zIndex ternary in ReadingProgress

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../chronicle/src/themes/paper/Layout.module.css |  1 +
 .../chronicle/src/themes/paper/Page.module.css   |  1 +
 .../src/themes/paper/ReadingProgress.tsx         | 16 +++++++++++++---
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/packages/chronicle/src/themes/paper/Layout.module.css b/packages/chronicle/src/themes/paper/Layout.module.css
index 0634eef9..ec9fd548 100644
--- a/packages/chronicle/src/themes/paper/Layout.module.css
+++ b/packages/chronicle/src/themes/paper/Layout.module.css
@@ -1,5 +1,6 @@
 .layout {
   --paper-sidebar-width: 260px;
+
   min-height: 100vh;
 }
 
diff --git a/packages/chronicle/src/themes/paper/Page.module.css b/packages/chronicle/src/themes/paper/Page.module.css
index a3d27f9f..9898167f 100644
--- a/packages/chronicle/src/themes/paper/Page.module.css
+++ b/packages/chronicle/src/themes/paper/Page.module.css
@@ -2,6 +2,7 @@
   --paper-navbar-height: 40px;
   --paper-navbar-padding: var(--rs-space-3);
   --paper-navbar-total: calc(var(--paper-navbar-height) + var(--paper-navbar-padding) * 2 + 1px);
+
   flex: 1;
   max-width: 1024px;
   margin: 0 auto;
diff --git a/packages/chronicle/src/themes/paper/ReadingProgress.tsx b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
index a2625000..09d5f3ca 100644
--- a/packages/chronicle/src/themes/paper/ReadingProgress.tsx
+++ b/packages/chronicle/src/themes/paper/ReadingProgress.tsx
@@ -43,14 +43,24 @@ function resolveOverlaps(headings: Heading[], maxPosition: number): Heading[] {
     lastUsedPos = newPos
   }
 
+  // Backward pass: clamp-and-shift to prevent overlapping positions
   for (let i = resolved.length - 1; i >= 0; i--) {
     const maxAllowed =
       i === resolved.length - 1
         ? maxPosition
         : resolved[i + 1].yPosition - TICK_HEIGHT
 
-    if (resolved[i].yPosition > maxAllowed) {
-      resolved[i] = { ...resolved[i], yPosition: Math.max(0, maxAllowed) }
+    const clampedPos = Math.max(0, maxAllowed)
+    if (resolved[i].yPosition > clampedPos) {
+      resolved[i] = { ...resolved[i], yPosition: clampedPos }
+      for (let j = i - 1; j >= 0; j--) {
+        const upperBound = resolved[j + 1].yPosition - TICK_HEIGHT
+        if (resolved[j].yPosition > upperBound) {
+          resolved[j] = { ...resolved[j], yPosition: Math.max(0, upperBound) }
+        } else {
+          break
+        }
+      }
     }
   }
 
@@ -235,7 +245,7 @@ export function ReadingProgress({ items }: ReadingProgressProps) {
               style={{
                 top: `${h.yPosition - 6}px`,
                 right: '24px',
-                zIndex: 10 * (h.level < 4 ? 1 : 0),
+                zIndex: h.level < 4 ? 10 : 0,
                 transitionDelay: `${50 * i}ms`,
               }}
             >