boltdocs 2.2.0 → 2.4.1

package/src/client/app/scroll-handler.tsx

@@ -11,29 +11,40 @@ export function ScrollHandler() {
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: pathname is used as a trigger for scroll-to-top on navigation
   useLayoutEffect(() => {
-    const container = document.querySelector('.boltdocs-content')
-    if (!container) return
+    const container = document.querySelector('.boltdocs-content') || window
+    
+    // Helper to get scroll top
+    const getScrollTop = () => {
+      if (container === window) return window.scrollY
+      return (container as HTMLElement).scrollTop
+    }
+    
+    // Helper to scroll
+    const scrollTo = (top: number, behavior: ScrollBehavior = 'auto') => {
+      if (container === window) {
+        window.scrollTo({ top, behavior })
+      } else {
+        (container as HTMLElement).scrollTo({ top, behavior })
+      }
+    }
 
     if (hash) {
       const id = hash.replace('#', '')
       const element = document.getElementById(id)
       if (element) {
         const offset = 80
-        const containerRect = container.getBoundingClientRect().top
+        const containerTop = container === window ? 0 : (container as HTMLElement).getBoundingClientRect().top
         const elementRect = element.getBoundingClientRect().top
-        const elementPosition = elementRect - containerRect
-        const offsetPosition = elementPosition - offset + container.scrollTop
+        const elementPosition = elementRect - containerTop
+        const offsetPosition = elementPosition - offset + getScrollTop()
 
-        container.scrollTo({
-          top: offsetPosition,
-          behavior: 'smooth',
-        })
+        scrollTo(offsetPosition, 'smooth')
         return
       }
     }
 
     // Scroll to top on navigation when no hash is specified
-    container.scrollTo(0, 0)
+    scrollTo(0)
   }, [pathname, hash])
 
   return null

package/src/client/app/theme-context.tsx

@@ -19,12 +19,15 @@ export function ThemeProvider({ children }: { children: React.ReactNode }) {
   useEffect(() => {
     setMounted(true)
     const stored = localStorage.getItem('boltdocs-theme') as Theme | null
-    const initialTheme = (stored === 'light' || stored === 'dark' || stored === 'system') ? stored : 'system'
-    
+    const initialTheme =
+      stored === 'light' || stored === 'dark' || stored === 'system'
+        ? stored
+        : 'system'
+
     setThemeState(initialTheme)
 
     const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
-    
+
     const updateResolved = (currentTheme: Theme, isDark: boolean) => {
       if (currentTheme === 'system') {
         setResolvedTheme(isDark ? 'dark' : 'light')
@@ -37,10 +40,11 @@ export function ThemeProvider({ children }: { children: React.ReactNode }) {
 
     const handleChange = (e: MediaQueryListEvent) => {
       // Re-read current theme state from some stable ref would be better, but we can capture it
-      // actually, the second useEffect will handle the source of truth, 
+      // actually, the second useEffect will handle the source of truth,
       // but this listener ensures 'system' updates instantly.
       setResolvedTheme((prevResolved) => {
-        const currentTheme = localStorage.getItem('boltdocs-theme') as Theme || 'system'
+        const currentTheme =
+          (localStorage.getItem('boltdocs-theme') as Theme) || 'system'
         if (currentTheme === 'system') {
           return e.matches ? 'dark' : 'light'
         }
@@ -56,8 +60,11 @@ export function ThemeProvider({ children }: { children: React.ReactNode }) {
   useEffect(() => {
     if (!mounted) return
 
-    const isSystemDark = window.matchMedia('(prefers-color-scheme: dark)').matches
-    const nextResolved = theme === 'system' ? (isSystemDark ? 'dark' : 'light') : theme
+    const isSystemDark = window.matchMedia(
+      '(prefers-color-scheme: dark)',
+    ).matches
+    const nextResolved =
+      theme === 'system' ? (isSystemDark ? 'dark' : 'light') : theme
 
     setResolvedTheme(nextResolved as 'light' | 'dark')
 

package/src/client/components/default-layout.tsx

@@ -5,7 +5,6 @@ import { OnThisPage } from '@components/ui-base/on-this-page'
 import { Head } from '@components/ui-base/head'
 import { Breadcrumbs } from '@components/ui-base/breadcrumbs'
 import { PageNav } from '@components/ui-base/page-nav'
-import { ProgressBar } from '@components/ui-base/progress-bar'
 import { ErrorBoundary } from '@components/ui-base/error-boundary'
 import { CopyMarkdown } from '@components/ui-base/copy-markdown'
 import { useRoutes } from '@client/hooks/use-routes'
@@ -40,10 +39,13 @@ export function DefaultLayout({ children }: LayoutProps) {
 
   return (
     <DocsLayout>
-      <ProgressBar />
       <Head
-        siteTitle={getTranslated(config.theme?.title, currentLocale) || 'Boltdocs'}
-        siteDescription={getTranslated(config.theme?.description, currentLocale) || ''}
+        siteTitle={
+          getTranslated(config.theme?.title, currentLocale) || 'Boltdocs'
+        }
+        siteDescription={
+          getTranslated(config.theme?.description, currentLocale) || ''
+        }
         routes={allRoutes}
       />
       <Navbar />

package/src/client/components/docs-layout.tsx

@@ -1,5 +1,6 @@
 import type React from 'react'
 import { cn } from '@client/utils/cn'
+import { useLocation } from '../hooks'
 
 /**
  * Props shared by all layout slot components.
@@ -60,17 +61,37 @@ function Content({ children, className, style }: SlotProps) {
     <main
       className={cn(
         'boltdocs-content flex-1 min-w-0 overflow-y-auto',
+        'contain-layout', // Optimization: isolate main content layout
         className,
       )}
       style={style}
     >
-      <div className="boltdocs-page mx-auto max-w-content-max pt-4 pb-20 px-4 sm:px-8">
-        {children}
-      </div>
+      {children}
     </main>
   )
 }
 
+/**
+ * MDX Content wrapper with standard page padding and max-width logic.
+ */
+function ContentMdx({ children, className, style }: SlotProps) {
+  const { pathname } = useLocation()
+  return (
+    <div
+      className={cn(
+        'boltdocs-page mx-auto pt-4 pb-20 px-4 sm:px-8',
+        {
+          'max-w-content-max': pathname.includes('/docs/'),
+        },
+        className,
+      )}
+      style={style}
+    >
+      {children}
+    </div>
+  )
+}
+
 /**
  * Content header row (breadcrumbs + copy markdown).
  */
@@ -96,10 +117,19 @@ function ContentFooter({ children, className, style }: SlotProps) {
   )
 }
 
+interface DocsLayoutComponent extends React.FC<SlotProps> {
+  Body: typeof Body
+  Content: typeof Content
+  ContentMdx: typeof ContentMdx
+  ContentHeader: typeof ContentHeader
+  ContentFooter: typeof ContentFooter
+}
+
 // Attach sub-components to the root
 export const DocsLayout = Object.assign(DocsLayoutRoot, {
   Body,
   Content,
+  ContentMdx,
   ContentHeader,
   ContentFooter,
-})
+}) as DocsLayoutComponent

package/src/client/components/icons-dev.tsx

@@ -72,3 +72,157 @@ export const Bluesky = (props: WrapperProps) => (
     <path d="M5.202 2.857C7.954 4.922 10.913 9.11 12 11.358c1.087-2.247 4.046-6.436 6.798-8.501C20.783 1.366 24 .213 24 3.883c0 .732-.42 6.156-.667 7.037-.856 3.061-3.978 3.842-6.755 3.37 4.854.826 6.089 3.562 3.422 6.299-5.065 5.196-7.28-1.304-7.847-2.97-.104-.305-.152-.448-.153-.327 0-.121-.05.022-.153.327-.568 1.666-2.782 8.166-7.847 2.97-2.667-2.737-1.432-5.473 3.422-6.3-2.777.473-5.899-.308-6.755-3.369C.42 10.04 0 4.615 0 3.883c0-3.67 3.217-2.517 5.202-1.026" />
   </svg>
 )
+
+// Icons file
+
+export const TypeScript = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'TypeScript'}</title>
+    <path
+      fill="#2563EB"
+      d="M3.234 9.093V7.318h8.363v1.775H8.479V17.5H6.352V9.093H3.234zm15.263 1.153c-.04-.4-.21-.712-.512-.934-.301-.222-.71-.333-1.228-.333-.351 0-.648.05-.89.149-.242.096-.427.23-.557.403a.969.969 0 0 0-.189.586.838.838 0 0 0 .115.477c.086.136.204.254.353.353.149.097.321.181.517.254.195.07.404.13.626.179l.915.219c.444.1.852.232 1.223.397.371.166.693.37.965.612.271.242.482.527.631.855.152.328.23.704.234 1.129-.004.623-.163 1.163-.478 1.62-.311.454-.762.807-1.352 1.06-.587.248-1.294.372-2.123.372-.822 0-1.538-.126-2.147-.378-.607-.252-1.081-.624-1.422-1.118-.338-.497-.516-1.112-.532-1.845h2.083c.023.342.12.627.293.855.176.226.41.397.701.513a2.8 2.8 0 0 0 1 .168c.364 0 .68-.053.949-.159a1.45 1.45 0 0 0 .631-.442c.15-.189.224-.406.224-.651a.846.846 0 0 0-.204-.577c-.132-.156-.328-.288-.586-.398a5.964 5.964 0 0 0-.94-.298l-1.109-.278c-.858-.21-1.536-.536-2.033-.98-.497-.444-.744-1.042-.74-1.795-.004-.616.16-1.155.491-1.615.335-.461.794-.82 1.377-1.08.584-.258 1.247-.387 1.99-.387.755 0 1.414.13 1.978.388.567.258 1.007.618 1.322 1.079.315.46.477.994.488 1.6h-2.064z"
+    />
+  </svg>
+)
+
+export const JavaScript = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'JavaScript'}</title>
+    <path
+      fill="#F59E0B"
+      d="M8.383 7.318h2.127v7.1c0 .656-.147 1.226-.442 1.71a2.924 2.924 0 01-1.218 1.118c-.52.262-1.125.393-1.815.393-.613 0-1.17-.107-1.67-.323a2.67 2.67 0 01-1.183-.994c-.292-.448-.436-1.01-.433-1.686h2.143c.006.269.061.5.164.691.106.19.25.335.432.438.186.1.405.15.657.15.265 0 .488-.057.67-.17.186-.116.327-.285.423-.507.096-.222.145-.496.145-.82v-7.1zm9.43 2.928c-.04-.4-.21-.712-.511-.934-.302-.222-.711-.333-1.228-.333-.352 0-.648.05-.89.149-.242.096-.428.23-.557.403a.969.969 0 00-.19.586.838.838 0 00.115.477c.087.136.204.254.353.353.15.097.322.181.517.254.196.07.405.13.627.179l.915.219c.444.1.851.232 1.223.397.37.166.692.37.964.612s.482.527.631.855a2.7 2.7 0 01.234 1.129c-.003.623-.162 1.163-.477 1.62-.312.454-.763.807-1.353 1.06-.586.248-1.294.372-2.122.372-.822 0-1.538-.126-2.148-.378-.607-.252-1.08-.624-1.422-1.118-.338-.497-.515-1.112-.532-1.845h2.083c.023.342.121.627.293.855.176.226.41.397.702.513.295.112.628.168.999.168.364 0 .68-.053.95-.159.271-.106.482-.253.63-.442.15-.189.224-.406.224-.651a.846.846 0 00-.203-.577c-.133-.156-.329-.288-.587-.398a5.964 5.964 0 00-.94-.298l-1.108-.278c-.859-.21-1.537-.536-2.034-.98-.497-.444-.744-1.042-.74-1.795-.004-.616.16-1.155.492-1.615.334-.461.793-.82 1.377-1.08.583-.258 1.246-.387 1.989-.387.755 0 1.415.13 1.978.388.567.258 1.008.618 1.323 1.079.314.46.477.994.487 1.6h-2.063z"
+    ></path>
+  </svg>
+)
+
+export const Json = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'JSON'}</title>
+    <path
+      fill="#F59E0B"
+      d="M4.778 6.667A2.667 2.667 0 017.444 4a.889.889 0 010 1.778.889.889 0 00-.888.889v3.5c0 .701-.273 1.35-.73 1.833.457.483.73 1.132.73 1.832v3.501c0 .491.398.89.888.89a.889.889 0 010 1.777 2.667 2.667 0 01-2.666-2.667v-3.5a.889.889 0 00-.674-.863l-.43-.108a.889.889 0 010-1.724l.43-.108a.889.889 0 00.674-.862V6.667zm14.222 0A2.667 2.667 0 0016.333 4a.889.889 0 000 1.778c.491 0 .89.398.89.889v3.5c0 .701.272 1.35.729 1.833a2.664 2.664 0 00-.73 1.832v3.501a.889.889 0 01-.889.89.889.889 0 000 1.777A2.667 2.667 0 0019 17.333v-3.5c0-.408.278-.764.673-.863l.431-.108a.889.889 0 000-1.724l-.43-.108a.889.889 0 01-.674-.862V6.667z"
+    ></path>
+  </svg>
+)
+
+export const Css = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'CSS'}</title>
+    <path
+      fill="#0EA5E9"
+      d="M4.778 6.667A2.667 2.667 0 017.444 4a.889.889 0 010 1.778.889.889 0 00-.888.889v3.5c0 .701-.273 1.35-.73 1.833.457.483.73 1.132.73 1.832v3.501c0 .491.398.89.888.89a.889.889 0 010 1.777 2.667 2.667 0 01-2.666-2.667v-3.5a.889.889 0 00-.674-.863l-.43-.108a.889.889 0 010-1.724l.43-.108a.889.889 0 00.674-.862V6.667zm14.222 0A2.667 2.667 0 0016.333 4a.889.889 0 000 1.778c.491 0 .89.398.89.889v3.5c0 .701.272 1.35.729 1.833a2.664 2.664 0 00-.73 1.832v3.501a.889.889 0 01-.889.89.889.889 0 000 1.777A2.667 2.667 0 0019 17.333v-3.5c0-.408.278-.764.673-.863l.431-.108a.889.889 0 000-1.724l-.43-.108a.889.889 0 01-.674-.862V6.667z"
+    ></path>
+  </svg>
+)
+
+export const BracketsOrange = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'HTML'}</title>
+    <path
+      fill="#EA580C"
+      d="M4.778 6.667A2.667 2.667 0 017.444 4a.889.889 0 010 1.778.889.889 0 00-.888.889v3.5c0 .701-.273 1.35-.73 1.833.457.483.73 1.132.73 1.832v3.501c0 .491.398.89.888.89a.889.889 0 010 1.777 2.667 2.667 0 01-2.666-2.667v-3.5a.889.889 0 00-.674-.863l-.43-.108a.889.889 0 010-1.724l.43-.108a.889.889 0 00.674-.862V6.667zm14.222 0A2.667 2.667 0 0016.333 4a.889.889 0 000 1.778c.491 0 .89.398.89.889v3.5c0 .701.272 1.35.729 1.833a2.664 2.664 0 00-.73 1.832v3.501a.889.889 0 01-.889.89.889.889 0 000 1.777A2.667 2.667 0 0019 17.333v-3.5c0-.408.278-.764.673-.863l.431-.108a.889.889 0 000-1.724l-.43-.108a.889.889 0 01-.674-.862V6.667z"
+    ></path>
+  </svg>
+)
+
+export default BracketsOrange
+
+export const React = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'React'}</title>
+    <path
+      fill="#0E8ADC"
+      d="M12 13.677a1.677 1.677 0 100-3.354 1.677 1.677 0 000 3.354z"
+    ></path>
+    <path
+      stroke="#0E8ADC"
+      d="M12 15.436c4.97 0 9-1.538 9-3.436s-4.03-3.436-9-3.436S3 10.102 3 12s4.03 3.436 9 3.436z"
+    ></path>
+    <path
+      stroke="#0E8ADC"
+      d="M9.024 13.718c2.485 4.305 5.832 7.025 7.476 6.076 1.644-.949.961-5.208-1.524-9.512C12.491 5.977 9.144 3.257 7.5 4.206c-1.644.949-.961 5.208 1.524 9.512z"
+    ></path>
+    <path
+      stroke="#0E8ADC"
+      d="M9.024 10.282c-2.485 4.304-3.168 8.563-1.524 9.512 1.644.95 4.99-1.771 7.476-6.076 2.485-4.304 3.168-8.563 1.524-9.512-1.644-.95-4.99 1.771-7.476 6.076z"
+    ></path>
+  </svg>
+)
+
+export const Markdown = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'Markdown'}</title>
+    <path
+      fill="#60A5FA"
+      d="M3 15.714V8h2.323l2.322 2.836L9.968 8h2.322v7.714H9.968V11.29l-2.323 2.836-2.322-2.836v4.424H3zm14.516 0l-3.484-3.743h2.323V8h2.322v3.97H21l-3.484 3.744z"
+    ></path>
+  </svg>
+)
+
+export const Shell = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 25 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'Shell'}</title>
+    <path
+      stroke="#14B8A6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth="2"
+      d="M4.336 17l6-6-6-6M12.336 19h8"
+    ></path>
+  </svg>
+)
+
+export const Yaml = (props: WrapperProps) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    fill="none"
+    viewBox="0 0 24 24"
+    {...wrapperProps(props)}
+  >
+    <title>{'YAML'}</title>
+    <path
+      fill="#A78BFA"
+      d="M6.533 5.864h2.755l2.654 5.011h.113l2.654-5.011h2.756l-4.245 7.522V17.5h-2.443v-4.114L6.533 5.864z"
+    ></path>
+  </svg>
+)

package/src/client/components/mdx/code-block.tsx

@@ -1,11 +1,38 @@
 import * as RAC from 'react-aria-components'
-import { Copy, Check } from 'lucide-react'
+import { Copy, Check, File } from 'lucide-react'
 import { cn } from '@client/utils/cn'
 import { useCodeBlock } from './hooks/use-code-block'
 import { useConfig } from '@client/app/config-context'
-import { CodeSandbox } from '@components/icons-dev'
+import {
+  CodeSandbox,
+  TypeScript,
+  JavaScript,
+  React as ReactIcon,
+  Json,
+  Css,
+  BracketsOrange,
+  Markdown,
+  Shell,
+  Yaml,
+} from '@components/icons-dev'
 import { Tooltip } from '@components/primitives/tooltip'
 
+const langIconMap: Record<string, React.ComponentType<{ size?: number }>> = {
+  ts: TypeScript,
+  tsx: ReactIcon,
+  js: JavaScript,
+  jsx: ReactIcon,
+  json: Json,
+  css: Css,
+  html: BracketsOrange,
+  md: Markdown,
+  mdx: Markdown,
+  bash: Shell,
+  sh: Shell,
+  yaml: Yaml,
+  yml: Yaml,
+}
+
 export interface CodeBlockProps {
   children?: React.ReactNode
   className?: string
@@ -15,6 +42,8 @@ export interface CodeBlockProps {
   title?: string
   lang?: string
   highlightedHtml?: string
+  'data-lang'?: string
+  plain?: boolean
   [key: string]: any
 }
 
@@ -25,11 +54,15 @@ export function CodeBlock(props: CodeBlockProps) {
     hideSandbox = true,
     hideCopy = false,
     highlightedHtml,
+    title,
+    'data-lang': dataLang,
+    plain = false,
     ...rest
   } = props
   const config = useConfig()
   const globalSandbox = config?.integrations?.sandbox
   const isSandboxEnabled = !!globalSandbox?.enable && !hideSandbox
+  const lang = props.lang || dataLang || ''
   const {
     copied,
     isExpanded,
@@ -41,13 +74,32 @@ export function CodeBlock(props: CodeBlockProps) {
     shouldTruncate,
   } = useCodeBlock(props)
 
+  const LangIcon = langIconMap[lang]
+
   return (
     <div
       className={cn(
-        'group relative my-6 overflow-hidden rounded-lg border border-border-subtle bg-(--color-code-bg)',
-        shouldTruncate && '[&>pre]:max-h-[250px] [&>pre]:overflow-hidden',
+        'group relative overflow-hidden bg-(--color-code-bg)',
+        'contain-layout contain-paint', // Optimization: isolate code block rendering
+        {
+          'my-6 rounded-lg border border-border-subtle': !plain,
+          '[&>pre]:max-h-62.5 [&>pre]:overflow-hidden': shouldTruncate,
+        },
+        props.className,
       )}
     >
+      {/* Title Header */}
+      {title && (
+        <div className="flex items-center gap-2 border-b border-border-subtle bg-bg-surface/50 px-4 py-2 text-[13px] font-medium text-text-muted">
+          {LangIcon ? (
+            <LangIcon size={14} />
+          ) : (
+            <File size={14} className="opacity-60" />
+          )}
+          <span>{title}</span>
+        </div>
+      )}
+
       {/* Toolbar */}
       <div className="absolute top-3 right-4 z-50 flex items-center gap-2 transition-all duration-300 opacity-0 group-hover:opacity-100">
         {isSandboxEnabled && (
@@ -66,7 +118,7 @@ export function CodeBlock(props: CodeBlockProps) {
             <RAC.Button
               onPress={handleCopy}
               className={cn(
-                'grid place-items-center w-8 h-8 bg-transparent outline-none cursor-pointer transition-all duration-200 hover:scale-115 active:scale-95 [&>svg]:w-5 [&>svg]:h-5 [&>svg]:stroke-2',
+                'grid place-items-center size-8 bg-transparent outline-none cursor-pointer transition-all duration-200 hover:scale-110 active:scale-95 [&>svg]:size-4 [&>svg]:stroke-2',
                 copied
                   ? 'text-emerald-400'
                   : 'text-text-muted hover:text-text-main',

package/src/client/components/mdx/component-preview.tsx

@@ -37,6 +37,7 @@ export function ComponentPreview(props: ComponentPreviewProps) {
             title={sandboxOptions.title}
             lang="tsx"
             highlightedHtml={highlightedHtml}
+            plain={true}
           >
             {initialCode}
           </CodeBlock>

package/src/client/components/mdx/file-tree.tsx

@@ -10,11 +10,39 @@ import {
 } from 'lucide-react'
 import { cn } from '@client/utils/cn'
 
+import {
+  TypeScript,
+  JavaScript,
+  React as ReactIcon,
+  Json,
+  Css,
+  BracketsOrange,
+  Markdown,
+  Shell,
+  Yaml,
+} from '@components/icons-dev'
+
 // --- Constants & Types ---
 
 const ICON_SIZE = 16
 const STROKE_WIDTH = 2
 
+const FILE_EXTENSION_MAP: Record<string, React.ComponentType<{ size?: number }>> = {
+  ts: TypeScript,
+  tsx: ReactIcon,
+  js: JavaScript,
+  jsx: ReactIcon,
+  json: Json,
+  css: Css,
+  html: BracketsOrange,
+  md: Markdown,
+  mdx: Markdown,
+  bash: Shell,
+  sh: Shell,
+  yaml: Yaml,
+  yml: Yaml,
+}
+
 const FILE_REGEXES = {
   CODE: /\.(ts|tsx|js|jsx|json|mjs|cjs|astro|vue|svelte)$/i,
   TEXT: /\.(md|mdx|txt)$/i,
@@ -68,6 +96,13 @@ function getFileIcon(filename: string, isFolder: boolean) {
     )
   }
 
+  // Check for specialized language icons
+  const extension = name.split('.').pop() || ''
+  const LangIcon = FILE_EXTENSION_MAP[extension]
+  if (LangIcon) {
+    return <LangIcon size={ICON_SIZE} />
+  }
+
   const fileIconClass = cn(
     iconClass,
     'text-text-dim group-hover:text-text-main',

package/src/client/components/primitives/helpers/observer.ts

@@ -14,51 +14,42 @@ export class Observer {
   private callback(entries: IntersectionObserverEntry[]) {
     if (entries.length === 0) return
 
-    let hasActive = false
-    this.items = this.items.map((item) => {
-      const entry = entries.find((entry) => entry.target.id === item.id)
-      let active = entry ? entry.isIntersecting : item.active && !item.fallback
-      if (this.single && hasActive) active = false
-
-      if (item.active !== active) {
-        item = {
-          ...item,
-          t: Date.now(),
-          active,
-          fallback: false,
-        }
+    // 1. Update internal state based on current intersection and position
+    for (const entry of entries) {
+      const item = this.items.find((i) => i.id === entry.target.id)
+      if (item) {
+        // item.active will track if the heading is currently "on or below" the trigger line
+        item.active = entry.isIntersecting
+
+        // item.fallback will track if the heading has scrolled "above" the trigger line
+        // RootMargin top is -100px, so trigger line is at 100px.
+        const activationLine = 100
+        item.fallback =
+          !entry.isIntersecting && entry.boundingClientRect.top < activationLine
       }
+    }
 
-      if (active) hasActive = true
-      return item
-    })
-
-    if (!hasActive && entries[0].rootBounds) {
-      const viewTop = entries[0].rootBounds.top
-      let min = Number.MAX_VALUE
-      let fallbackIdx = -1
-
-      for (let i = 0; i < this.items.length; i++) {
-        const element = document.getElementById(this.items[i].id)
-        if (!element) continue
-
-        const d = Math.abs(viewTop - element.getBoundingClientRect().top)
-        if (d < min) {
-          fallbackIdx = i
-          min = d
-        }
+    // 2. The active heading is the LAST one in document order that has scrolled past the line.
+    let highlightIdx = -1
+    for (let i = this.items.length - 1; i >= 0; i--) {
+      if (this.items[i].fallback) {
+        highlightIdx = i
+        break
       }
+    }
 
-      if (fallbackIdx !== -1) {
-        this.items[fallbackIdx] = {
-          ...this.items[fallbackIdx],
-          active: true,
-          fallback: true,
-          t: Date.now(),
-        }
-      }
+    // 3. Initial state: If no headings have passed the line yet, default to the first heading.
+    if (highlightIdx === -1 && this.items.length > 0) {
+      highlightIdx = 0
     }
 
+    // 4. Map back to UI state
+    this.items = this.items.map((item, idx) => ({
+      ...item,
+      active: idx === highlightIdx,
+      t: idx === highlightIdx ? Date.now() : item.t,
+    }))
+
     this.onChange?.()
   }
 

package/src/client/components/primitives/index.ts

@@ -12,6 +12,7 @@ export * from './menu'
 export * from './popover'
 export * from './tooltip'
 export * from './link'
+export * from './skeleton'
 export { Separator, ToggleButton } from 'react-aria-components'
 
 export { cn } from '../../utils/cn'