docs/src/hooks/use-code-overlay.tsx (1)

26-33: Simplify navigation-close logic; avoid extra state churn

Tracking currentPage in state causes an extra effect run. Use a ref for the previous pathname.

-  const [currentPage, setCurrentPage] = useState('');
+  const prevPathRef = useRef<string | null>(null);
   const pathname = usePathname();
 
   // Close overlay when navigating to a different page
   useEffect(() => {
-    if (pathname !== currentPage && currentPage !== '') {
-      setIsOpen(false);
-    }
-    setCurrentPage(pathname);
-  }, [pathname, currentPage]);
+    if (prevPathRef.current && pathname !== prevPathRef.current) {
+      setIsOpen(false);
+    }
+    prevPathRef.current = pathname;
+  }, [pathname]);

docs/src/components/mdx/dynamic-code-block-overlay.tsx (4)

172-181: Improve accessibility: add landmark and relationships

Declare a landmark and link the header title for screen readers. Also expose expanded state.

-      <div
+      <div
         className={cn(
           "fixed bottom-0 bg-fd-background border-t border-fd-border z-50",
           "transition-all duration-300 ease-out",
           "shadow-2xl",
           "flex flex-col", // Add flex container
           // Position to avoid sidebar overlap - adjust based on sidebar state
           "left-0 right-0",
           isMainSidebarCollapsed ? "md:left-16" : "md:left-64"
         )}
         style={{
           maxHeight: getOptimalHeight(), // Use maxHeight instead of fixed height
         }}
+        role="region"
+        aria-labelledby="dynamic-codeblock-overlay-title"
+        aria-expanded={isExpanded}
       >
...
-              <h3 className="font-semibold text-fd-foreground text-sm sm:text-base truncate">{title}</h3>
+              <h3 id="dynamic-codeblock-overlay-title" className="font-semibold text-fd-foreground text-sm sm:text-base truncate">{title}</h3>

Also applies to: 206-214, 156-170

---

120-136: Avoid state updates after unmount for copy timeout

Store the timeout id and clear it on unmount.

-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
...
   const [copied, setCopied] = useState(false);
+  const copyTimeoutRef = useRef<number | null>(null);
...
   const handleCopy = () => {
     const copyToClipboard = async () => {
       try {
         await navigator.clipboard.writeText(code);
         setCopied(true);
-        setTimeout(() => setCopied(false), 2000);
+        if (copyTimeoutRef.current) clearTimeout(copyTimeoutRef.current);
+        copyTimeoutRef.current = window.setTimeout(() => setCopied(false), 2000);
       } catch (error) {
         // Handle clipboard error gracefully
         console.error('Failed to copy code:', error instanceof Error ? error.message : 'Unknown error');
         // Could show a toast notification here in the future
       }
     };
 
     // Run async function - all errors are handled within the function
     runAsynchronously(copyToClipboard);
   };
+
+  useEffect(() => {
+    return () => {
+      if (copyTimeoutRef.current) clearTimeout(copyTimeoutRef.current);
+    };
+  }, []);

---

72-86: Throttle resize handler to reduce layout work on rapid resizes

Current listener updates state on every event. Throttle to an animation frame or a short timeout.

-  useEffect(() => {
-    const updateWindowSize = () => {
-      setWindowSize({ width: window.innerWidth, height: window.innerHeight });
-    };
+  useEffect(() => {
+    let rafId = 0;
+    const updateWindowSize = () => {
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(() => {
+        setWindowSize({ width: window.innerWidth, height: window.innerHeight });
+      });
+    };
...
-    return () => window.removeEventListener('resize', updateWindowSize);
+    return () => {
+      cancelAnimationFrame(rafId);
+      window.removeEventListener('resize', updateWindowSize);
+    };
   }, []);

---

220-224: Theme consistency

Hardcoded #0a0a0a may clash with theming. Prefer a design token or Tailwind var consistent with the docs theme.

-            style={{
-              background: '#0a0a0a'
-            }}
+            className="bg-fd-code"  /* or bg-neutral-950 if available */

docs/src/components/layouts/docs.tsx (1)

1357-1373: LGTM with a minor optimization option

Renderer correctly closes on toggle and reads context safely. Optional: lazy-load the overlay to shave initial JS.

- import { DynamicCodeblockOverlay } from '../mdx/dynamic-code-block-overlay';
+ import dynamic from 'next/dynamic';
+ const DynamicCodeblockOverlay = dynamic(
+   () => import('../mdx/dynamic-code-block-overlay').then(m => m.DynamicCodeblockOverlay),
+   { ssr: false }
+ );

docs/src/components/mdx/dynamic-code-block.tsx (7)

4-4: Defer Shiki to reduce bundle size.

import { codeToHtml } from "shiki" eagerly pulls a heavy dependency into the client bundle even when useOverlay is true (no inline highlight). Dynamically import Shiki inside the effect.

-import { codeToHtml } from "shiki";
+// Defer Shiki to when inline highlighting is needed

@@
   useEffect(() => {
     const updateHighlightedCode = async () => {
       try {
-        const html = await codeToHtml(code, {
+        const { codeToHtml } = await import('shiki');
+        const html = await codeToHtml(code, {
           lang: language,
           theme: 'github-dark',

Also applies to: 84-104

---

151-154: Remove ineffective !important in inline style.

!important doesn’t work in React inline styles and is redundant with Tailwind classes already applied.

-        <div
-          className="rounded-lg border bg-[#0a0a0a] p-4 overflow-auto max-h-[500px] text-sm"
-          style={{
-            background: '#0a0a0a !important',
-          }}
-        >
+        <div
+          className="rounded-lg border bg-[#0a0a0a] p-4 overflow-auto max-h-[500px] text-sm"
+        >

---

12-16: Make auto-open user/configurable.

Auto-opening can feel intrusive. Expose a prop to control it.

 type DynamicCodeblockProps = {
   code: string,
   language?: string,
   title?: string,
   useOverlay?: boolean,
+  autoOpen?: boolean,
 }
 
-export function DynamicCodeblock({ code, language = 'tsx', title, useOverlay = true }: DynamicCodeblockProps) {
+export function DynamicCodeblock({ code, language = 'tsx', title, useOverlay = true, autoOpen = true }: DynamicCodeblockProps) {
@@
-  useEffect(() => {
-    if (useOverlay && code && !hasInitialized) {
+  useEffect(() => {
+    if (useOverlay && autoOpen && code && !hasInitialized) {
       const timer = setTimeout(() => {
         openOverlay(code, language, title);
         setHasInitialized(true);
       }, 100);
       return () => clearTimeout(timer);
     }
-  }, [useOverlay, code, language, title, openOverlay, hasInitialized]);
+  }, [useOverlay, autoOpen, code, language, title, openOverlay, hasInitialized]);

Also applies to: 62-74

---

75-81: Avoid redundant overlay refreshes.

Prevent repeated openOverlay calls when props haven’t effectively changed.

+  const [lastOverlayKey, setLastOverlayKey] = useState<string | null>(null);
@@
-  useEffect(() => {
-    if (useOverlay && code && hasInitialized && isOpen) {
-      openOverlay(code, language, title);
-    }
-  }, [code, language, title, useOverlay, openOverlay, hasInitialized, isOpen]);
+  useEffect(() => {
+    if (!useOverlay || !code || !hasInitialized || !isOpen) return;
+    const key = `${language}|${title}|${code}`;
+    if (key !== lastOverlayKey) {
+      openOverlay(code, language, title);
+      setLastOverlayKey(key);
+    }
+  }, [code, language, title, useOverlay, openOverlay, hasInitialized, isOpen, lastOverlayKey]);

---

24-37: Throttle the resize listener.

Directly setting state on every resize event can cause jank. Throttle via rAF.

   useEffect(() => {
-    const updateWindowWidth = () => {
-      setWindowWidth(window.innerWidth);
-    };
+    let raf = 0;
+    const updateWindowWidth = () => {
+      if (raf) return;
+      raf = requestAnimationFrame(() => {
+        raf = 0;
+        setWindowWidth(window.innerWidth);
+      });
+    };
@@
-    return () => window.removeEventListener('resize', updateWindowWidth);
+    return () => {
+      window.removeEventListener('resize', updateWindowWidth);
+      if (raf) cancelAnimationFrame(raf);
+    };
   }, []);

---

39-61: Prefer IntersectionObserver for near-bottom detection.

A sentinel with IntersectionObserver is cheaper than per-scroll math and respects passive behavior.

I can provide a small useNearBottom hook using an invisible footer sentinel if you want it bundled in this PR.

---

120-143: Disable the trigger when no code is available.

Avoid opening an empty overlay and improve a11y.

-    return !isOpen ? (
+    return !isOpen ? (
       <button
-        onClick={() => openOverlay(code, language, title)}
-        className="fixed bottom-6 z-30 flex items-center gap-1.5 px-3 py-2 bg-fd-primary text-fd-primary-foreground rounded-full shadow-lg hover:scale-105 active:scale-95 transition-all duration-300 border border-fd-primary/20"
+        onClick={() => code?.trim() && openOverlay(code, language, title)}
+        disabled={!code?.trim()}
+        aria-disabled={!code?.trim()}
+        className="fixed bottom-6 z-30 flex items-center gap-1.5 px-3 py-2 bg-fd-primary text-fd-primary-foreground rounded-full shadow-lg hover:scale-105 active:scale-95 transition-all duration-300 border border-fd-primary/20 disabled:opacity-50 disabled:pointer-events-none"

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

docs/src/components/mdx/dynamic-code-block-overlay.tsx (3)

35-41: SSR-safe window usage looks good

Guarded access avoids hydration pitfalls; sensible defaults used.

---

32-34: Nice: memoized line count

Addresses the earlier perf note.

---

92-119: Sanitize highlighted HTML and escape fallback to prevent XSS

dangerouslySetInnerHTML renders raw HTML. Sanitize the Shiki output and HTML‑escape the fallback to avoid XSS in docs.

Apply within this range:

-        setHighlightedCode(html);
+        setHighlightedCode(DOMPurify.sanitize(html));
       } catch (error) {
         console.error('Error highlighting code:', error);
-        setHighlightedCode(`<pre><code>${code}</code></pre>`);
+        setHighlightedCode(`<pre><code>${escapeHtml(code)}</code></pre>`);

Additions outside this range:

// Top-level import
+import DOMPurify from "isomorphic-dompurify";

// Helper (module-local; place near the component)
+function escapeHtml(input: string): string {
+  return input
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}

docs/src/components/mdx/dynamic-code-block-overlay.tsx (6)

231-233: Document sanitization and suppress the lint warning in place

Keep dangerouslySetInnerHTML but annotate that content is sanitized to satisfy Biome.

           <div
             className="[&_*]:!bg-transparent [&_pre]:!bg-transparent [&_code]:!bg-transparent text-xs sm:text-sm leading-[1.4] sm:leading-[1.5] [&_pre]:text-xs [&_pre]:sm:text-sm [&_code]:text-xs [&_code]:sm:text-sm [&_pre]:leading-[1.4] [&_pre]:sm:leading-[1.5] [&_code]:leading-[1.4] [&_code]:sm:leading-[1.5] [&_pre]:m-0 [&_pre]:p-0 [&_pre]:overflow-visible"
-              dangerouslySetInnerHTML={{ __html: highlightedCode }}
+              {/* biome-ignore lint/security/noDangerouslySetInnerHtml: Shiki HTML sanitized with DOMPurify above */}
+              dangerouslySetInnerHTML={{ __html: highlightedCode }}
           />

---

143-153: Attach Escape key listener only when overlay is open

Avoid a global listener when closed; simpler handler too.

-useEffect(() => {
-  const handleEscape = (e: KeyboardEvent) => {
-    if (e.key === 'Escape' && isOpen) {
-      onToggle?.(false);
-    }
-  };
-  document.addEventListener('keydown', handleEscape);
-  return () => document.removeEventListener('keydown', handleEscape);
-}, [isOpen, onToggle]);
+useEffect(() => {
+  if (!isOpen) return;
+  const handleEscape = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') onToggle?.(false);
+  };
+  document.addEventListener('keydown', handleEscape);
+  return () => document.removeEventListener('keydown', handleEscape);
+}, [isOpen, onToggle]);

---

75-91: Throttle resize recalcs to reduce layout thrash

Use rAF to coalesce rapid resize events.

 useEffect(() => {
   const updateWindowSize = () => {
     if (typeof window !== 'undefined') {
       setWindowSize({ width: window.innerWidth, height: window.innerHeight });
     }
   };
 
   // Set initial window size
   updateWindowSize();
 
   // Add resize listener
-  window.addEventListener('resize', updateWindowSize);
+  let raf = 0;
+  const onResize = () => {
+    cancelAnimationFrame(raf);
+    raf = requestAnimationFrame(updateWindowSize);
+  };
+  window.addEventListener('resize', onResize);
 
-  return () => window.removeEventListener('resize', updateWindowSize);
+  return () => {
+    cancelAnimationFrame(raf);
+    window.removeEventListener('resize', onResize);
+  };
 }, []);

---

162-176: Add dialog semantics for accessibility

Mark the overlay as a modal dialog; improves SR navigation.

-      <div
+      <div
         className={cn(
           "fixed bottom-0 bg-fd-background border-t border-fd-border z-50",
           "transition-all duration-300 ease-out",
           "shadow-2xl",
           "flex flex-col", // Add flex container
           // Position to avoid sidebar overlap - adjust based on sidebar state
           "left-0 right-0",
           isMainSidebarCollapsed ? "md:left-16" : "md:left-64"
         )}
         style={{
           maxHeight: getOptimalHeight(), // Use maxHeight instead of fixed height
         }}
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        tabIndex={-1}
       >

---

3-3: Avoid deep import path to shared package

Deep imports are brittle; prefer the package entrypoint if available.

-import { runAsynchronously } from "@stackframe/stack-shared/dist/utils/promises";
+import { runAsynchronously } from "@stackframe/stack-shared/utils/promises";

---

92-119: Reduce bundle size by lazy-loading Shiki

Defer Shiki until needed to keep docs’ initial JS smaller.

Example:

// move import out; lazy-load inside the effect
useEffect(() => {
  const updateHighlightedCode = async () => {
    try {
      const { codeToHtml } = await import("shiki/bundle/web");
      const html = await codeToHtml(code, { /* ... */ });
      setHighlightedCode(DOMPurify.sanitize(html));
    } catch (e) {
      setHighlightedCode(`<pre><code>${escapeHtml(code)}</code></pre>`);
    }
  };
  runAsynchronously(updateHighlightedCode());
}, [code, language]);

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.