boltdocs 1.10.2 → 1.11.0

package/src/client/components/ui-base/error-boundary.tsx

@@ -0,0 +1,52 @@
+import type { ErrorInfo, ReactNode } from 'react'
+import { Component } from 'react'
+
+import { Button } from '../primitives'
+
+interface Props {
+  children?: ReactNode
+  fallback?: ReactNode
+}
+
+interface State {
+  hasError: boolean
+  error?: Error
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  public state: State = { hasError: false }
+
+  public static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error }
+  }
+
+  public componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('Uncaught error in Boltdocs Layout:', error, errorInfo)
+  }
+
+  public render() {
+    if (this.state.hasError) {
+      return (
+        this.props.fallback || (
+          <div className="flex flex-col items-center justify-center min-h-[40vh] text-center gap-4 px-4">
+            <div className="text-lg font-bold text-red-400">
+              Something went wrong
+            </div>
+            <p className="text-sm text-text-muted max-w-md">
+              {this.state.error?.message ||
+                'An unexpected error occurred while rendering this page.'}
+            </p>
+            <Button
+              className="rounded-lg border border-border-subtle bg-bg-surface px-5 py-2 text-sm font-medium text-text-main transition-colors hover:bg-bg-muted cursor-pointer"
+              onPress={() => this.setState({ hasError: false })}
+            >
+              Try again
+            </Button>
+          </div>
+        )
+      )
+    }
+
+    return this.props.children
+  }
+}

package/src/client/components/ui-base/github-stars.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react'
+import { getStarsRepo } from '@client/utils/github'
+import { Github } from '@components/icons-dev'
+
+export function GithubStars({ repo }: { repo: string }) {
+  const [stars, setStars] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (repo) {
+      getStarsRepo(repo)
+        .then((stars) => setStars(stars))
+        .catch(() => setStars('0'))
+    }
+  }, [repo])
+
+  return (
+    <a
+      href={`https://github.com/${repo}`}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="inline-flex items-center gap-2 rounded-md border border-border-subtle bg-bg-surface px-2.5 py-1.5 text-xs font-medium text-text-muted transition-all hover:bg-bg-main hover:border-border-strong hover:text-text-main"
+    >
+      <Github className="h-4 w-4" />
+      {stars && <span className="tabular-nums">{stars}</span>}
+    </a>
+  )
+}

package/src/client/components/ui-base/head.tsx

@@ -0,0 +1,69 @@
+import { useEffect } from 'react'
+import { useLocation } from 'react-router-dom'
+
+interface HeadProps {
+  siteTitle: string
+  siteDescription?: string
+  routes: Array<{ path: string; title: string; description?: string }>
+}
+
+export function Head({ siteTitle, siteDescription, routes }: HeadProps) {
+  const location = useLocation()
+
+  useEffect(() => {
+    // Find the current route's metadata
+    const currentRoute = routes.find((r) => r.path === location.pathname)
+    const pageTitle = currentRoute?.title
+    const pageDescription = currentRoute?.description || siteDescription || ''
+
+    // Update document title
+    document.title = pageTitle ? `${pageTitle} | ${siteTitle}` : siteTitle
+
+    // Update or create meta description
+    let metaDesc = document.querySelector(
+      'meta[name="description"]',
+    ) as HTMLMetaElement | null
+    if (!metaDesc) {
+      metaDesc = document.createElement('meta')
+      metaDesc.name = 'description'
+      document.head.appendChild(metaDesc)
+    }
+    metaDesc.content = pageDescription
+
+    // Update OG tags
+    setMetaTag('property', 'og:title', document.title)
+    setMetaTag('property', 'og:description', pageDescription)
+    setMetaTag('property', 'og:type', 'article')
+    setMetaTag('property', 'og:url', window.location.href)
+
+    // Twitter card
+    setMetaTag('name', 'twitter:card', 'summary')
+    setMetaTag('name', 'twitter:title', document.title)
+    setMetaTag('name', 'twitter:description', pageDescription)
+
+    // Canonical URL
+    let canonical = document.querySelector(
+      'link[rel="canonical"]',
+    ) as HTMLLinkElement | null
+    if (!canonical) {
+      canonical = document.createElement('link')
+      canonical.rel = 'canonical'
+      document.head.appendChild(canonical)
+    }
+    canonical.href = window.location.origin + location.pathname
+  }, [location.pathname, siteTitle, siteDescription, routes])
+
+  return null // This component only manages <head>, no visual output
+}
+
+function setMetaTag(attr: 'name' | 'property', key: string, content: string) {
+  let tag = document.querySelector(
+    `meta[${attr}="${key}"]`,
+  ) as HTMLMetaElement | null
+  if (!tag) {
+    tag = document.createElement('meta')
+    tag.setAttribute(attr, key)
+    document.head.appendChild(tag)
+  }
+  tag.content = content
+}

package/src/client/components/ui-base/loading.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * A premium loading component that includes an SVG fill animation
+ * and a synchronized progress indicator.
+ *
+ * It features a glassmorphism container and a Bolt-style SVG logo
+ * with a dynamic fill effect.
+ */
+export function Loading() {
+  const [progress, setProgress] = useState(0)
+
+  useEffect(() => {
+    let currentProgress = 0
+    let up = true
+
+    const interval = setInterval(() => {
+      if (up) {
+        currentProgress += 1
+        if (currentProgress >= 100) {
+          currentProgress = 100
+          up = false
+        }
+      } else {
+        currentProgress -= 1
+        if (currentProgress <= 0) {
+          currentProgress = 0
+          up = true
+        }
+      }
+      setProgress(currentProgress)
+    }, 20)
+
+    return () => clearInterval(interval)
+  }, [])
+
+  const clipPathValue = `inset(${100 - progress}% 0 0 0)`
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[60vh] p-4 text-center">
+      <div className="relative group">
+        <div className="relative inline-block">
+          {/* SVG Background (Dimmed Base) */}
+          <svg
+            className="w-24 h-auto opacity-10 filter grayscale brightness-50"
+            viewBox="0 0 60 51"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            role="img"
+            aria-hidden="true"
+          >
+            <title>Loading indicator background</title>
+            <path
+              d="M29.4449 0H19.4449V16.5L29.4449 6.5V0Z"
+              fill="currentColor"
+            />
+            <path
+              d="M26.9449 22.7265C26.9449 22.5077 21.2201 27.0658 16.9449 28.5C13.7491 29.5721 12.3156 29.5038 8.94486 29.5C5.59532 29.4963 0 28.5 0 28.5C0 28.5 5.57953 28.5146 8.94486 27.5C12.5409 26.4158 14.8203 25.5843 17.9449 23.5C23.3445 19.898 29.4449 11.5 29.4449 11.5L29.9449 18C29.9449 18 33.5825 15.8308 36.4449 15C39.4452 14.1291 44.4449 14 44.4449 14C44.4449 14 36.9449 19 34.4449 21.5C31.5322 24.4126 29.8582 26.9017 29.4449 31C29.1217 34.2041 29.4771 36.4508 31.4449 39C33.5792 41.765 35.952 43.0183 39.4449 43C42.677 42.9831 45.3003 42.4182 47.4449 40C49.7406 37.4113 50.2495 34.4466 49.9449 31C49.6603 27.7804 48.4876 25.4953 45.9449 23.5C43.2931 21.4191 36.4449 24 36.4449 24L47.9449 15C47.9449 15 51.5761 16.771 53.4449 18.5C55.711 20.5967 56.7467 22.1546 57.9449 25C59.1784 27.9295 59.4832 29.8216 59.4449 33C59.4089 35.9867 59.179 37.78 57.9449 40.5C56.8475 42.9185 55.8511 44.6507 53.9449 46.5C51.9236 48.4609 50.5803 49.0076 47.9449 50C45.5414 50.9051 44.0131 51 41.4449 51C38.8766 51 37.3235 50.9685 34.9449 50C32.4851 48.9985 29.4449 46 29.4449 46V51H19.4449V37.9904L22.9449 31.4226L26.9449 22.7265Z"
+              fill="currentColor"
+            />
+          </svg>
+
+          {/* SVG Animated (Vibrant Fill Overlay) */}
+          <svg
+            className="absolute top-0 left-0 w-24 h-auto text-primary-500 drop-shadow-[0_0_20px_rgba(var(--primary-rgb),0.5)] transition-[clip-path] duration-100 ease-linear"
+            style={{ clipPath: clipPathValue }}
+            viewBox="0 0 60 51"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            role="img"
+            aria-hidden="true"
+          >
+            <title>Loading indicator animated fill</title>
+            <path
+              d="M29.4449 0H19.4449V16.5L29.4449 6.5V0Z"
+              fill="currentColor"
+            />
+            <path
+              d="M26.9449 22.7265C26.9449 22.5077 21.2201 27.0658 16.9449 28.5C13.7491 29.5721 12.3156 29.5038 8.94486 29.5C5.59532 29.4963 0 28.5 0 28.5C0 28.5 5.57953 28.5146 8.94486 27.5C12.5409 26.4158 14.8203 25.5843 17.9449 23.5C23.3445 19.898 29.4449 11.5 29.4449 11.5L29.9449 18C29.9449 18 33.5825 15.8308 36.4449 15C39.4452 14.1291 44.4449 14 44.4449 14C44.4449 14 36.9449 19 34.4449 21.5C31.5322 24.4126 29.8582 26.9017 29.4449 31C29.1217 34.2041 29.4771 36.4508 31.4449 39C33.5792 41.765 35.952 43.0183 39.4449 43C42.677 42.9831 45.3003 42.4182 47.4449 40C49.7406 37.4113 50.2495 34.4466 49.9449 31C49.6603 27.7804 48.4876 25.4953 45.9449 23.5C43.2931 21.4191 36.4449 24 36.4449 24L47.9449 15C47.9449 15 51.5761 16.771 53.4449 18.5C55.711 20.5967 56.7467 22.1546 57.9449 25C59.1784 27.9295 59.4832 29.8216 59.4449 33C59.4089 35.9867 59.179 37.78 57.9449 40.5C56.8475 42.9185 55.8511 44.6507 53.9449 46.5C51.9236 48.4609 50.5803 49.0076 47.9449 50C45.5414 50.9051 44.0131 51 41.4449 51C38.8766 51 37.3235 50.9685 34.9449 50C32.4851 48.9985 29.4449 46 29.4449 46V51H19.4449V37.9904L22.9449 31.4226L26.9449 22.7265Z"
+              fill="currentColor"
+            />
+          </svg>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/client/components/ui-base/navbar.tsx

@@ -0,0 +1,138 @@
+import { Suspense, lazy } from 'react'
+import { useNavbar } from '@hooks/use-navbar'
+import { useVersion } from '@hooks/use-version'
+import { useI18n } from '@hooks/use-i18n'
+import { useRoutes } from '@hooks/use-routes'
+import NavbarPrimitive from '@components/primitives/navbar'
+import { ThemeToggle } from './theme-toggle'
+import { GithubStars } from './github-stars'
+import { Tabs } from './tabs'
+import { useLocation } from 'react-router-dom'
+import type { BoltdocsSocialLink } from '@node/config'
+import Menu from '@components/primitives/menu'
+import { Button } from '@components/primitives/button'
+import { ChevronDown } from 'lucide-react'
+import { useConfig } from '@client/app/config-context'
+
+const SearchDialog = lazy(() =>
+  import('./search-dialog').then((m) => ({
+    default: m.SearchDialog,
+  })),
+)
+
+export function Navbar() {
+  const { links, title, logo, logoProps, github, social, config } = useNavbar()
+  const { routes, allRoutes, currentVersion, currentLocale } = useRoutes()
+  const { pathname } = useLocation()
+  const { themeConfig } = useConfig()
+
+  const hasTabs = themeConfig?.tabs && themeConfig.tabs.length > 0
+
+  return (
+    <NavbarPrimitive.NavbarRoot className={hasTabs ? 'border-b-0' : ''}>
+      <NavbarPrimitive.Content>
+        <NavbarPrimitive.NavbarLeft>
+          <NavbarPrimitive.NavbarLogo
+            src={logo ?? ''}
+            alt={logoProps?.alt || title}
+            width={logoProps?.width ?? 24}
+            height={logoProps?.height ?? 24}
+          />
+          <NavbarPrimitive.Title>{title}</NavbarPrimitive.Title>
+
+          {config.versions && currentVersion && <NavbarVersion />}
+
+          <NavbarPrimitive.Links>
+            {links.map((link) => (
+              <NavbarPrimitive.Link key={link.href} {...(link as any)} />
+            ))}
+          </NavbarPrimitive.Links>
+        </NavbarPrimitive.NavbarLeft>
+        <NavbarPrimitive.NavbarCenter>
+          <Suspense
+            fallback={
+              <div className="h-9 w-32 animate-pulse rounded-md bg-bg-surface" />
+            }
+          >
+            <SearchDialog routes={routes || []} />
+          </Suspense>
+        </NavbarPrimitive.NavbarCenter>
+        <NavbarPrimitive.NavbarRight>
+          {config.i18n && currentLocale && <NavbarI18n />}
+          <NavbarPrimitive.Split />
+          <ThemeToggle />
+          {github && <GithubStars repo={themeConfig?.githubRepo ?? ''} />}
+          {social.length > 0 && <NavbarPrimitive.Split />}
+          <div className="flex items-center gap-1">
+            {social.map(({ icon, link }: BoltdocsSocialLink) => (
+              <NavbarPrimitive.Socials
+                key={link}
+                icon={icon}
+                link={link}
+                className="p-1.5"
+              />
+            ))}
+          </div>
+        </NavbarPrimitive.NavbarRight>
+      </NavbarPrimitive.Content>
+
+      {pathname !== '/' && hasTabs && config.themeConfig?.tabs && (
+        <div className="w-full border-b border-border-subtle bg-bg-main">
+          <Tabs
+            tabs={config.themeConfig.tabs}
+            routes={allRoutes || routes || []}
+          />
+        </div>
+      )}
+    </NavbarPrimitive.NavbarRoot>
+  )
+}
+
+function NavbarVersion() {
+  const { currentVersionLabel, availableVersions, handleVersionChange } =
+    useVersion()
+
+  if (availableVersions.length === 0) return null
+
+  return (
+    <Menu.Trigger>
+      <Button variant={'outline'} iconPosition="right" icon={<ChevronDown />}>
+        {currentVersionLabel}
+      </Button>
+      <Menu.Section items={availableVersions}>
+        {(version) => (
+          <Menu.Item
+            key={`${version.value ?? ''}`}
+            onPress={() => handleVersionChange(version.value)}
+          >
+            {version.label as string}
+          </Menu.Item>
+        )}
+      </Menu.Section>
+    </Menu.Trigger>
+  )
+}
+
+function NavbarI18n() {
+  const { currentLocaleLabel, availableLocales, handleLocaleChange } = useI18n()
+
+  if (availableLocales.length === 0) return null
+
+  return (
+    <Menu.Trigger>
+      <Button variant={'outline'} iconPosition="right" icon={<ChevronDown />}>
+        {currentLocaleLabel}
+      </Button>
+      <Menu.Section items={availableLocales}>
+        {(locale) => (
+          <Menu.Item
+            key={`${locale.value ?? ''}`}
+            onPress={() => handleLocaleChange(locale.value)}
+          >
+            {locale.label as string}
+          </Menu.Item>
+        )}
+      </Menu.Section>
+    </Menu.Trigger>
+  )
+}

package/src/client/components/ui-base/not-found.tsx

@@ -0,0 +1,24 @@
+import { ArrowLeft } from 'lucide-react'
+import { Link } from '@components/primitives/link'
+
+export function NotFound() {
+  return (
+    <div className="flex items-center justify-center min-h-[60vh] text-center">
+      <div className="space-y-4">
+        <span className="text-8xl font-black tracking-tighter text-primary-500/20">
+          404
+        </span>
+        <h1 className="text-2xl font-bold text-text-main">Page Not Found</h1>
+        <p className="text-sm text-text-muted max-w-sm mx-auto">
+          The page you're looking for doesn't exist or has been moved.
+        </p>
+        <Link
+          href="/"
+          className="inline-flex items-center gap-2 rounded-lg bg-primary-500 px-5 py-2.5 text-sm font-semibold text-white outline-none transition-all hover:brightness-110 hover:shadow-lg focus-visible:ring-2 focus-visible:ring-primary-500/30"
+        >
+          <ArrowLeft size={16} /> Go to Home
+        </Link>
+      </div>
+    </div>
+  )
+}

package/src/client/components/ui-base/on-this-page.tsx

@@ -0,0 +1,152 @@
+import OTP, {
+  AnchorProvider,
+  ScrollProvider,
+  useActiveAnchor,
+} from '@components/primitives/on-this-page'
+import React, { useRef, useEffect, useState, useCallback } from 'react'
+import { useOnThisPage } from '@hooks/use-onthispage'
+import type { OnThisPageProps } from '@client/types'
+import { Pencil, CircleHelp, TextAlignStart } from 'lucide-react'
+
+export function OnThisPage({
+  headings: rawHeadings = [],
+  editLink,
+  communityHelp,
+  filePath,
+}: OnThisPageProps) {
+  const { headings } = useOnThisPage(rawHeadings)
+
+  const toc = React.useMemo(
+    () =>
+      headings.map((h) => ({ title: h.text, url: `#${h.id}`, depth: h.level })),
+    [headings],
+  )
+
+  if (headings.length === 0) return null
+
+  return (
+    <AnchorProvider toc={toc}>
+      <OnThisPageInner
+        headings={headings}
+        editLink={editLink}
+        communityHelp={communityHelp}
+        filePath={filePath}
+      />
+    </AnchorProvider>
+  )
+}
+
+function OnThisPageInner({
+  headings,
+  editLink,
+  communityHelp,
+  filePath,
+}: OnThisPageProps & {
+  headings: { level: number; text: string; id: string }[]
+}) {
+  const activeId = useActiveAnchor()
+  const [indicatorStyle, setIndicatorStyle] = useState<React.CSSProperties>({
+    opacity: 0,
+  })
+  const listRef = useRef<HTMLUListElement>(null)
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!activeId || !listRef.current) return
+
+    const activeLink = listRef.current.querySelector(
+      `a[href="#${activeId}"]`,
+    ) as HTMLElement
+
+    if (activeLink) {
+      setIndicatorStyle({
+        transform: `translateY(${activeLink.offsetTop}px)`,
+        height: `${activeLink.offsetHeight}px`,
+        opacity: 1,
+      })
+    }
+  }, [activeId])
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+      e.preventDefault()
+      const el = document.getElementById(id)
+
+      if (el) {
+        el.scrollIntoView({ behavior: 'smooth' })
+        window.history.pushState(null, '', `#${id}`)
+      }
+    },
+    [],
+  )
+
+  return (
+    <OTP.OnThisPageRoot>
+      <OTP.OnThisPageHeader className="flex flex-row gap-x-2">
+        <TextAlignStart size={16} />
+        On this page
+      </OTP.OnThisPageHeader>
+      <ScrollProvider containerRef={scrollContainerRef}>
+        <OTP.OnThisPageContent
+          className="max-h-[450px] boltdocs-otp-scroll-area"
+          ref={scrollContainerRef}
+        >
+          <OTP.OnThisPageIndicator style={indicatorStyle} />
+          <ul
+            className="relative space-y-2 border-l border-border-subtle"
+            ref={listRef}
+          >
+            {headings.map((h) => (
+              <OTP.OnThisPageItem key={h.id} level={h.level}>
+                <OTP.OnThisPageLink
+                  href={`#${h.id}`}
+                  active={activeId === h.id}
+                  onClick={(e) => handleClick(e, h.id)}
+                  className="pl-4"
+                >
+                  {h.text}
+                </OTP.OnThisPageLink>
+              </OTP.OnThisPageItem>
+            ))}
+          </ul>
+        </OTP.OnThisPageContent>
+      </ScrollProvider>
+
+      {(editLink || communityHelp) && (
+        <div className="mt-8 pt-8 border-t border-border-subtle space-y-4">
+          <p className="text-xs font-bold uppercase tracking-wider text-text-main">
+            Need help?
+          </p>
+          <ul className="space-y-3">
+            {editLink && filePath && (
+              <li>
+                <a
+                  href={editLink.replace(':path', filePath)}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="flex items-center gap-2 text-sm text-text-muted hover:text-text-main transition-colors"
+                >
+                  <Pencil size={16} />
+                  Edit this page
+                </a>
+              </li>
+            )}
+            {communityHelp && (
+              <li>
+                <a
+                  href={communityHelp}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="flex items-center gap-2 text-sm text-text-muted hover:text-text-main transition-colors"
+                >
+                  <CircleHelp size={16} />
+                  Community help
+                </a>
+              </li>
+            )}
+          </ul>
+        </div>
+      )}
+    </OTP.OnThisPageRoot>
+  )
+}

package/src/client/components/ui-base/page-nav.tsx

@@ -0,0 +1,39 @@
+import { usePageNav } from '@hooks/use-page-nav'
+import PageNavPrimitive from '@components/primitives/page-nav'
+
+/**
+ * Component to display the previous and next page navigation buttons.
+ */
+export function PageNav() {
+  const { prevPage, nextPage } = usePageNav()
+
+  if (!prevPage && !nextPage) return null
+
+  return (
+    <PageNavPrimitive.PageNavRoot>
+      {prevPage ? (
+        <PageNavPrimitive.PageNavLink to={prevPage.path} direction="prev">
+          <PageNavPrimitive.PageNavLink.Title>
+            Previous
+          </PageNavPrimitive.PageNavLink.Title>
+          <PageNavPrimitive.PageNavLink.Description>
+            {prevPage.title}
+          </PageNavPrimitive.PageNavLink.Description>
+        </PageNavPrimitive.PageNavLink>
+      ) : (
+        <div />
+      )}
+
+      {nextPage && (
+        <PageNavPrimitive.PageNavLink to={nextPage.path} direction="next">
+          <PageNavPrimitive.PageNavLink.Title>
+            Next
+          </PageNavPrimitive.PageNavLink.Title>
+          <PageNavPrimitive.PageNavLink.Description>
+            {nextPage.title}
+          </PageNavPrimitive.PageNavLink.Description>
+        </PageNavPrimitive.PageNavLink>
+      )}
+    </PageNavPrimitive.PageNavRoot>
+  )
+}

package/src/client/components/ui-base/powered-by.tsx

@@ -0,0 +1,19 @@
+import { Zap } from 'lucide-react'
+
+export function PoweredBy() {
+  return (
+    <div className="rounded-full px-4 py-2 bg-gray-100 text-xs text-gray-500 flex items-center gap-1 mt-6 justify-center">
+      <a
+        href="https://github.com/jesusalcaladev/boltdocs"
+        target="_blank"
+        rel="noopener noreferrer"
+        className="flex items-center gap-1"
+      >
+        <Zap className="powered-by-icon" size={12} fill="currentColor" />
+        <span>
+          Powered by <strong>Boltdocs</strong>
+        </span>
+      </a>
+    </div>
+  )
+}

package/src/client/components/ui-base/progress-bar.tsx

@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react'
+import { ProgressBar as AriaProgressBar } from 'react-aria-components'
+
+/**
+ * A reading progress bar component that tracks the scroll position
+ * within the Boltdocs content area.
+ *
+ * It utilizes react-aria-components for accessibility and is fixed
+ * to the top of the viewport for a premium, non-intrusive UI experience.
+ */
+export function ProgressBar() {
+  const [progress, setProgress] = useState(0)
+
+  useEffect(() => {
+    let container: Element | null = null
+    let timer: NodeJS.Timeout
+
+    const handleScroll = () => {
+      if (!container) return
+      const { scrollTop, scrollHeight, clientHeight } = container
+      if (scrollHeight <= clientHeight) {
+        setProgress(0)
+        return
+      }
+      const scrollPercent = (scrollTop / (scrollHeight - clientHeight)) * 100
+      setProgress(Math.min(100, Math.max(0, scrollPercent)))
+    }
+
+    const attachListener = () => {
+      // Find the main content area for Boltdocs
+      container = document.querySelector('.boltdocs-content')
+      if (container) {
+        container.addEventListener('scroll', handleScroll)
+        handleScroll()
+        if (timer) clearInterval(timer)
+        return true
+      }
+      return false
+    }
+
+    // Since the container might not be present at mount (if content is lazy loaded),
+    // we poll until it's found or the component unmounts.
+    if (!attachListener()) {
+      timer = setInterval(attachListener, 100)
+    }
+
+    return () => {
+      if (container) container.removeEventListener('scroll', handleScroll)
+      if (timer) clearInterval(timer)
+    }
+  }, [])
+
+  return (
+    <AriaProgressBar
+      value={progress}
+      aria-label="Reading progress"
+      className="fixed top-0 left-0 right-0 z-999 h-0.5 bg-transparent w-full pointer-events-none"
+    >
+      {({ percentage }) => (
+        <div
+          className="h-full bg-primary-500 transition-[width] duration-300 ease-out shadow-[0_0_8px_rgba(var(--primary-rgb),0.4)]"
+          style={{ width: `${percentage}%` }}
+        />
+      )}
+    </AriaProgressBar>
+  )
+}