fix(docs): fix Core Web Vitals regressions on docs.sim.ai

Empirically measured under real trace-based (devtools) CPU/network
throttling against the live site: mobile Performance 59, LCP 9.2s
(TTFB 745ms + 8.4s element render delay).

- sidebar-components.tsx / [lang]/layout.tsx: the docs sidebar renders
  every page in the doc tree as a link at once. Next's default
  viewport-prefetch fired an RSC payload fetch for every one of them on
  initial load - dozens of concurrent requests competing with the page's
  own content for bandwidth. Wired fumadocs' documented `sidebar.prefetch`
  option through to the custom SidebarItem/SidebarFolder components (which
  were bypassing it entirely, using next/link directly with no prefetch
  prop) via the `useSidebar()` context hook.
- video.tsx: `autoPlay` forces browsers to fetch the full video file
  immediately on mount regardless of `preload`. Gated actual src loading
  behind an IntersectionObserver so a page with several of these doesn't
  pull down every video up front (5MB across 3 requests, in this case).
  Single shared component - fixes every doc page that embeds one.
- proxy.ts: the i18n middleware matcher excluded favicon/robots.txt/etc
  but not `icon.svg`, so every request for it got routed through i18n
  negotiation instead of served as a static file, 404ing in production.
- next.config.ts: enable productionBrowserSourceMaps - safe since this
  repo's source is already fully public, real debuggability benefit,
  zero performance cost.
- shiki 4.0.0 -> 4.3.1 (verified: syntax highlighting still renders
  correctly). Attempted a coordinated fumadocs-core/ui/mdx/openapi
  upgrade to latest; fumadocs-openapi's v11 factory function became
  client-only (breaking change beyond its declared peer deps, requiring
  a component-boundary restructure), so only the safe, verified,
  docs-exclusive bumps (fumadocs-core/ui/mdx, shiki) are included here -
  the openapi major bump needs its own dedicated migration PR.

Verified via a real production build (dummy env, all 3974 pages
including API reference render/build cleanly) and a clean (non-stale)
local server: Performance 59 -> 71 measured under real devtools
throttling, RSC prefetch requests 63 -> 11, video requests/bytes 3/5MB
-> 0. A pre-existing React hydration warning (#418) was found and
confirmed present on live production before any of these changes,
unrelated to this diff - documented, not blocking.

Author: waleedlatif1

apps/docs/app/[lang]/layout.tsx

@@ -110,6 +110,12 @@ export default async function Layout({ children, params }: LayoutProps) {
               collapsible: false,
               footer: null,
               banner: null,
+              // The sidebar renders every page in the doc tree as a link at
+              // once, so Next's default viewport-prefetch behavior fires an
+              // RSC payload fetch for every one of them on initial load -
+              // dozens of concurrent requests competing with the actual
+              // page's own content for bandwidth on a real connection.
+              prefetch: false,
               components: {
                 Item: SidebarItem,
                 Folder: SidebarFolder,

apps/docs/components/docs-layout/sidebar-components.tsx

@@ -2,6 +2,7 @@
 
 import { type ReactNode, useState } from 'react'
 import type { Folder, Item, Separator } from 'fumadocs-core/page-tree'
+import { useSidebar } from 'fumadocs-ui/components/sidebar/base'
 import Link from 'next/link'
 import { usePathname } from 'next/navigation'
 import { i18n } from '@/lib/i18n'
@@ -66,11 +67,13 @@ const FOLDER_ACTIVE = 'lg:bg-[var(--surface-active)] lg:text-[var(--text-body)]'
 
 export function SidebarItem({ item }: { item: Item }) {
   const pathname = usePathname()
+  const { prefetch } = useSidebar()
   const active = isActive(item.url, pathname, false)
 
   return (
     <Link
       href={item.url}
+      prefetch={prefetch}
       data-active={active}
       className={cn(
         ITEM_BASE,
@@ -97,6 +100,7 @@ function isApiReferenceFolder(node: Folder): boolean {
 
 export function SidebarFolder({ item, children }: { item: Folder; children: ReactNode }) {
   const pathname = usePathname()
+  const { prefetch } = useSidebar()
   const hasActiveChild = checkHasActiveChild(item, pathname)
   const isApiRef = isApiReferenceFolder(item)
   const isOnApiRefPage = stripLangPrefix(pathname).startsWith('/api-reference')
@@ -111,6 +115,7 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
     return (
       <Link
         href={item.index.url}
+        prefetch={prefetch}
         data-active={active}
         className={cn(
           ITEM_BASE,
@@ -133,6 +138,7 @@ export function SidebarFolder({ item, children }: { item: Folder; children: Reac
           <>
             <Link
               href={item.index.url}
+              prefetch={prefetch}
               data-active={active}
               className={cn(
                 'flex flex-1 items-center gap-2 rounded-md px-2 py-1.5 text-sm transition-colors',

apps/docs/components/ui/video.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { cn, getAssetUrl } from '@/lib/utils'
 import { Lightbox } from './lightbox'
 
@@ -30,6 +30,27 @@ export function Video({
   const videoRef = useRef<HTMLVideoElement>(null)
   const startTimeRef = useRef(0)
   const [isLightboxOpen, setIsLightboxOpen] = useState(false)
+  const [isInView, setIsInView] = useState(false)
+
+  useEffect(() => {
+    const el = videoRef.current
+    if (!el) return
+
+    // `autoPlay` forces browsers to fetch the full file immediately on mount
+    // regardless of `preload` - gate the actual load behind the viewport so a
+    // page with several of these doesn't pull down every video up front.
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setIsInView(true)
+          observer.disconnect()
+        }
+      },
+      { rootMargin: '200px' }
+    )
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [])
 
   const openLightbox = () => {
     startTimeRef.current = videoRef.current?.currentTime ?? 0
@@ -39,17 +60,18 @@ export function Video({
   const video = (
     <video
       ref={videoRef}
-      autoPlay={autoPlay}
+      autoPlay={isInView && autoPlay}
       loop={loop}
       muted={muted}
       playsInline={playsInline}
+      preload='none'
       width={width}
       height={height}
       className={cn(
         className,
         enableLightbox && 'cursor-pointer transition-opacity group-hover:opacity-[0.97]'
       )}
-      src={getAssetUrl(src)}
+      src={isInView ? getAssetUrl(src) : undefined}
     />
   )
 

apps/docs/next.config.ts

@@ -5,6 +5,10 @@ const withMDX = createMDX()
 
 const config: NextConfig = {
   reactStrictMode: true,
+  // Safe here since this repo's source is already fully public on GitHub -
+  // no additional exposure versus Next's default (disabled to avoid leaking
+  // source on the client).
+  productionBrowserSourceMaps: true,
   transpilePackages: ['@sim/emcn', '@sim/workflow-renderer'],
   images: {
     unoptimized: true,

apps/docs/package.json

@@ -36,7 +36,7 @@
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "remark-breaks": "^4.0.0",
-    "shiki": "4.0.0",
+    "shiki": "4.3.1",
     "streamdown": "2.5.0",
     "tailwind-merge": "^3.0.2",
     "reactflow": "^11.11.4",

apps/docs/proxy.ts

@@ -20,6 +20,6 @@ export default function proxy(request: NextRequest, event: NextFetchEvent) {
 
 export const config = {
   matcher: [
-    '/((?!api|_next/static|_next/image|favicon|static|robots.txt|sitemap.xml|llms.txt|llms-full.txt).*)',
+    '/((?!api|_next/static|_next/image|favicon|icon.svg|static|robots.txt|sitemap.xml|llms.txt|llms-full.txt).*)',
   ],
 }