• docs/src/components/homepage/iconHover.tsx
• docs/src/app/docs/[[...slug]]/page.tsx
• docs/src/components/layouts/docs-header-wrapper.tsx

docs/src/app/docs/[[...slug]]/page.tsx (1)

14-25: Consider performance implications of calling source.getPages() on every redirect.

The helper function calls source.getPages() on every request to /docs without a slug. If this isn't internally cached by fumadocs, it could impact performance. Consider computing this value once at build time or memoizing the result.

You could cache the result:

+let cachedDefaultUrl: string | null | undefined;
+
 function getDefaultDocsRedirectUrl(): string | null {
+  if (cachedDefaultUrl !== undefined) {
+    return cachedDefaultUrl;
+  }
+
   const pages = source.getPages();
   // Prefer an overview page if one exists without platform prefix
   const overviewPage = pages.find(page => page.url === '/docs/overview');
   if (overviewPage) {
-    return overviewPage.url;
+    cachedDefaultUrl = overviewPage.url;
+    return cachedDefaultUrl;
   }
 
   // Fall back to the first docs page in the collection
   const firstDocsPage = pages.find(page => page.url.startsWith('/docs/'));
-  return firstDocsPage?.url ?? null;
+  cachedDefaultUrl = firstDocsPage?.url ?? null;
+  return cachedDefaultUrl;
 }

docs/src/components/layouts/docs-header-wrapper.tsx (3)

183-229: Improve key generation for recursive tree items.

Lines 205 and 218 use child.type === 'page' ? child.url : index for keys. Falling back to array index for non-page items (folders, separators) can cause React reconciliation issues when the tree structure changes.

Consider generating stable keys for all node types:

-            <MobilePageTreeItem key={child.type === 'page' ? child.url : index} item={child} />
+            <MobilePageTreeItem key={child.type === 'page' ? child.url : (child.type === 'folder' ? `folder-${child.name}-${index}` : `sep-${index}`)} item={child} />

Or extract a helper function to generate consistent keys:

function getNodeKey(node: PageTree.Node, index: number): string {
  if (node.type === 'page') return node.url;
  if (node.type === 'folder') return `folder-${node.name}-${index}`;
  return `separator-${node.name || index}`;
}

Then use: key={getNodeKey(child, index)}

---

231-241: Same key generation issue as MobilePageTreeItem.

Line 237 has the same fallback-to-index key pattern. Consider applying the same stable key generation strategy suggested for MobilePageTreeItem.

---

251-279: Memoize docsSection to prevent unnecessary recalculations.

Line 254 computes docsSection on every render. Since it only depends on pathname and is used in the sectionTree memoization (line 255), wrapping it with useMemo would prevent unnecessary re-filtering of the tree when other props change.

Apply this diff:

  const navLinks = useMemo(() => generateNavLinks(), []);
- const docsSection = resolveDocsSection(pathname);
+ const docsSection = useMemo(() => resolveDocsSection(pathname), [pathname]);
  const sectionTree = useMemo(() => (pageTree ? filterTreeForSection(pageTree, docsSection) : undefined), [pageTree, docsSection]);

docs/src/components/layouts/shared/section-utils.ts (2)

8-10: Replace RegExp constructor with literal regex.

Creating a RegExp via constructor on every call is less efficient than a literal regex. Since PLATFORM_PREFIX is a compile-time constant, compile the entire pattern once.

+const SDK_SECTION_REGEX = /^\/docs\/(?:[a-z-]+\/)?sdk(?:\/.*)?$/;
+
 export function isInSdkSection(pathname: string): boolean {
-  return new RegExp(`^/docs/${PLATFORM_PREFIX}sdk(?:/.*)?$`).test(pathname);
+  return SDK_SECTION_REGEX.test(pathname);
 }

This also addresses the static analysis ReDoS warning by eliminating runtime regex construction.

---

12-14: Replace RegExp constructors with literal regexes.

Same issue as isInSdkSection: use literal regexes for better performance.

+const COMPONENTS_SECTION_REGEX = /^\/docs\/(?:[a-z-]+\/)?components(?:\/.*)?$/;
+const CUSTOMIZATION_SECTION_REGEX = /^\/docs\/(?:[a-z-]+\/)?customization(?:\/.*)?$/;
+
 export function isInComponentsSection(pathname: string): boolean {
-  return new RegExp(`^/docs/${PLATFORM_PREFIX}components(?:/.*)?$`).test(pathname);
+  return COMPONENTS_SECTION_REGEX.test(pathname);
 }

 export function isInCustomizationSection(pathname: string): boolean {
-  return new RegExp(`^/docs/${PLATFORM_PREFIX}customization(?:/.*)?$`).test(pathname);
+  return CUSTOMIZATION_SECTION_REGEX.test(pathname);
 }

Also applies to: 20-22

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

344-344: Consider renaming platformColor to reflect its new purpose.

The variable name platformColor is now misleading since platform-specific logic has been removed. Consider renaming to accentColor, primaryColor, or similar to better reflect that it's now a static theme color.

-const platformColor = 'rgb(59, 130, 246)';
+const accentColor = 'rgb(59, 130, 246)';

Then update all references to use the new name.

Also applies to: 444-444, 600-600

docs/.gitignore (1)

8-8: Remove the ignore rule for src/lib/platform-navigation.ts from docs/.gitignore. No file or references named “platform-navigation.ts” exist in the repo, so the entry is now stale.

docs/src/components/layouts/docs-layout-router.tsx (1)

42-43: Compute section and sectionTree lazily to skip filtering for API docs.

Move

const section = resolveDocsSection(pathname);
const sectionTree = useMemo(() => filterTreeForSection(props.tree, section), [props.tree, section]);

below the if (isInApiSection…) check (i.e. inside the non-API branches) so you don’t run filterTreeForSection when rendering the API layout.

docs/content/docs/(guides)/getting-started/production.mdx (1)

45-47: Brand casing: Gitlab → GitLab.

Align with official brand spelling.

-<TabsTrigger value="gitlab">Gitlab</TabsTrigger>
+<TabsTrigger value="gitlab">GitLab</TabsTrigger>
...
-    <TabsContent value="gitlab">
+    <TabsContent value="gitlab">
       [GitLab OAuth Setup Guide](https://docs.gitlab.com/ee/integration/oauth_provider.html)

Also applies to: 96-101

docs/src/components/mdx/simple-platform-example.mdx (1)

90-98: Trailing comment inside object literal is fine, but consider block style for consistency.

Not a blocker; consider /* Override default */ for consistency with MDX/JSX comment style.

docs/content/docs/(guides)/concepts/auth-providers/twitch.mdx (1)

17-31: Add local redirect URI example for dev.
Including a localhost redirect reduces first‑run friction.

-  5. Under **OAuth Redirect URLs**, add `https://api.stack-auth.com/api/v1/auth/oauth/callback/twitch`
+  5. Under **OAuth Redirect URLs**, add:
+     - `https://api.stack-auth.com/api/v1/auth/oauth/callback/twitch` (production)
+     - `http://localhost:3000/api/v1/auth/oauth/callback/twitch` (development; adjust port as needed)

docs/content/docs/(guides)/overview.mdx (2)

7-8: Use extensionless docs link.
Avoid .mdx in routes to prevent 404s.

-You can get started in five minutes with our [setup guide](./getting-started/setup.mdx), or jump straight into the documentation.
+You can get started in five minutes with our [setup guide](./getting-started/setup), or jump straight into the documentation.

---

17-34: Remove deprecated IF_PLATFORM markers.
Platform gating is gone; keep both cards visible and drop the comment noise.

-  {/* IF_PLATFORM: react-like */}
   <Card 
     title="Components"
     icon="fa-solid fa-puzzle"
     href="./components"
   >
     Use our pre-built React components, or create your own
   </Card>
-  {/* END_PLATFORM */}
-  {/* IF_PLATFORM: js-like */}
   <Card 
     title="SDK Reference"
     icon="fa-regular fa-file-lines" 
     href="./sdk"
   >
     Learn how to use Stack Auth's SDK
   </Card>
-  {/* END_PLATFORM */}

docs/content/docs/(guides)/concepts/auth-providers/spotify.mdx (1)

22-35: Add dev redirect URI for completeness.
Parity with other guides and smoother local testing.

-  5. Under **Redirect URI**, add `https://api.stack-auth.com/api/v1/auth/oauth/callback/spotify`
+  5. Under **Redirect URI**, add:
+     - `https://api.stack-auth.com/api/v1/auth/oauth/callback/spotify` (production)
+     - `http://localhost:3000/api/v1/auth/oauth/callback/spotify` (development; adjust port as needed)

docs/content/docs/(guides)/concepts/auth-providers/gitlab.mdx (1)

28-32: Self‑hosted instance field: add label/example.

Add the expected field label and an example (e.g., https://gitlab.example.com) to reduce confusion.

docs/content/docs/components/sign-in.mdx (1)

1-4: Frontmatter: full: true behavior.

Verify the docs theme respects full: true for layout; otherwise drop it to avoid layout mismatch.

docs/content/docs/(guides)/customization/page-examples/index.mdx (1)

10-15: Add direct links to the example pages for fast navigation.

Listing the child pages prevents orphaning and improves crawl/search relevance. Suggest linking to sign-in, sign-up, forgot-password, and password-reset here.

 Browse the examples to learn how to:
 
 - Create custom sign-in pages
 - Build custom sign-up forms  
 - Implement password reset flows
 - Handle forgotten password scenarios
+
+## Examples
+
+- [Sign-in](./sign-in)
+- [Sign-up](./sign-up)
+- [Forgot password](./forgot-password)
+- [Password reset](./password-reset)

docs/content/docs/sdk/types/team-profile.mdx (1)

25-37: Clarify nullability semantics for profile fields.

State whether empty strings are ever returned vs null, and note size/format constraints for profileImageUrl to reduce ambiguity for integrators.

-      The display name of the user within the team context as a `string` or `null` if no display name is set.
+      The display name of the user within the team context as a `string`, or `null` if unset.
+      Note: empty string (`""`) is not returned by the API — prefer `null` checks. Max length: 128 chars. [If different, update here.]

docs/content/docs/sdk/types/project.mdx (1)

57-76: Document config default values and server-only fields.

Add defaults and whether these flags are server-only or exposed to clients. Reduces guesswork and aligns SDK expectations.

-      <ParamField path="signUpEnabled" type="boolean">
-        Indicates if sign-up is enabled for the project.
+      <ParamField path="signUpEnabled" type="boolean" default={true}>
+        Indicates if sign-up is enabled for the project. Default: `true`.
       </ParamField>
@@
-      <ParamField path="credentialEnabled" type="boolean">
-        Specifies if credential-based authentication is enabled for the project.
+      <ParamField path="credentialEnabled" type="boolean" default={true}>
+        Specifies if credential-based authentication is enabled. Default: `true`.
       </ParamField>
@@
-      <ParamField path="magicLinkEnabled" type="boolean">
-        States whether magic link authentication is enabled for the project.
+      <ParamField path="magicLinkEnabled" type="boolean" default={false}>
+        Whether magic link authentication is enabled. Default: `false`.
       </ParamField>
@@
-      <ParamField path="clientTeamCreationEnabled" type="boolean">
-        Determines if client-side team creation is permitted within the project.
+      <ParamField path="clientTeamCreationEnabled" type="boolean" default={false}>
+        If client-side team creation is permitted. Default: `false`. Server-managed in admin UI.
       </ParamField>
@@
-      <ParamField path="clientUserDeletionEnabled" type="boolean">
-        Indicates if client-side user deletion is enabled for the project.
+      <ParamField path="clientUserDeletionEnabled" type="boolean" default={false}>
+        If client-side user deletion is enabled. Default: `false`. Server-managed in admin UI.
       </ParamField>

docs/content/docs/(guides)/concepts/auth-providers/google.mdx (1)

24-27: Add local development redirect URI and environment variable names.

Improves time-to-success and parity across environments.

-    7. Under **Authorized redirect URIs**, add `https://api.stack-auth.com/api/v1/auth/oauth/callback/google`
+    7. Under **Authorized redirect URIs**, add:
+       - Production: `https://api.stack-auth.com/api/v1/auth/oauth/callback/google`
+       - Local dev (example): `http://localhost:3000/api/v1/auth/oauth/callback/google`
@@
-    9. Save the **Client ID** and **Client Secret** that are displayed.
+    9. Save the **Client ID** and **Client Secret** that are displayed (e.g., `STACK_GOOGLE_CLIENT_ID`, `STACK_GOOGLE_CLIENT_SECRET`).

-    3. Set the **Client ID** and **Client Secret** you obtained from Google Cloud Console earlier.
+    3. Set the **Client ID** and **Client Secret** you obtained from Google Cloud Console earlier.
+    4. (Optional) Restrict scopes as needed; default `openid email profile` works for basic sign-in.

docs/content/docs/sdk/types/team-user.mdx (3)

16-19: Make platform note explicit and rearrange calls for broader applicability.

List generic API first, then framework-specific hooks, and clarify that the hook is only available in React-like environments.

-It is usually obtained by calling 
-`team.useUsers()` or {/* THIS_LINE_PLATFORM react-like */}
-`team.listUsers()` on a [`Team` object](../types/team.mdx#team).
+You can obtain users via:
+- `team.listUsers()` on a [`Team` object](../types/team.mdx#team).
+- `team.useUsers()` {/* React-only hook */} in React-like environments for subscription-driven UIs.

---

67-74: Unify link target style for ServerUser across page and ToC.

In ToC you use ./user#serveruser, elsewhere ../types/user.mdx#serveruser. Prefer one pattern to avoid mismatches in link resolvers.

-  & ServerUser //$stack-link-to:./user#serveruser
+  & ServerUser //$stack-link-to:../types/user#serveruser

---

1-12: Update broken-link check to resolve links per file directory
The current script prepends docs/content globally, so ../../components/stack-provider.mdx is flagged “missing” even though it exists at docs/content/docs/components/stack-provider.mdx. Adjust your validation to resolve each relative link against its MDX file’s directory so that ../../components/stack-provider.mdx in docs/content/docs/sdk/... correctly maps to the actual location.

docs/content/docs/components/index.mdx (1)

118-118: Unindent the “Teams & Organizations” heading.

Four leading spaces turn this heading into a code block, so it vanishes from the document outline. Align it flush-left (matching the other headings) to get proper heading styling and navigation anchors.

-    ## Teams & Organizations
+  ## Teams & Organizations

docs/src/components/mdx/platform-config.ts (1)

2-9: Consider using ES6 Map for better type safety and adherence to coding guidelines.

The nested object structure for PlatformConfig doesn't align with the coding guideline to "prefer ES6 Map over Record when representing key–value collections." While objects work here, using Maps would provide better type safety, built-in iteration, and clearer semantics for dynamic key-value lookups.

As per coding guidelines.

Consider refactoring to:

export type PlatformConfig = Map<string, Map<string, {
  defaultFilename?: string,
  language: string,
}>>

This would require updating the initialization and helper functions, but provides better runtime guarantees and aligns with the guideline.

docs/content/docs/(guides)/getting-started/users.mdx (1)

19-19: Use JSX-style comment for consistency.

Line 19 uses a plain comment inside JSX content, which may cause parsing issues depending on the MDX version. For safety and consistency with line 35 (which uses a similar comment in a JSX context), use a JSX-style comment block.

Apply this fix:

 `user.listTeams()` functions. The created team will then inherit the permissions of that user; for example, the `team.update(...)` function can only succeed if the user is allowed to make updates to the team.
+{/* or: user.useTeams() */}
-`user.listTeams()` functions. The created team will then inherit the permissions of that user; for example, the `team.update(...)` function can only succeed if the user is allowed to make updates to the team.

Or if the comment is intended as inline documentation, keep it but ensure it's properly formatted:

-`user.useTeams()` or {/* THIS_LINE_PLATFORM react-like */}
+{/* THIS_LINE_PLATFORM react-like */}
+`user.useTeams()` or
 `user.listTeams()` functions. The created team will then inherit the permissions of that user; for example, the `team.update(...)` function can only succeed if the user is allowed to make updates to the team.

docs/src/components/mdx/platform-codeblock.tsx (5)

25-31: Avoid listener map leaks; delete empty entries.

remove*Listener leaves empty arrays in the Map; over time this grows across mounts.

Apply this diff:

 function removePlatformListener(id: string, listener: PlatformChangeListener): void {
   const list = platformListeners.get(id) ?? [];
-  platformListeners.set(
-    id,
-    list.filter((item) => item !== listener),
-  );
+  const next = list.filter((item) => item !== listener);
+  if (next.length) platformListeners.set(id, next);
+  else platformListeners.delete(id);
 }
@@
 function removeFrameworkListener(id: string, listener: FrameworkChangeListener): void {
   const list = frameworkListeners.get(id) ?? [];
-  frameworkListeners.set(
-    id,
-    list.filter((item) => item !== listener),
-  );
+  const next = list.filter((item) => item !== listener);
+  if (next.length) frameworkListeners.set(id, next);
+  else frameworkListeners.delete(id);
 }

Also applies to: 39-45

---

181-182: Use slice instead of deprecated substr.

Minor nit; avoid deprecated substr.

Apply this diff:

-  const [componentId] = useState(() => Math.random().toString(36).substr(2, 9));
+  const [componentId] = useState(() => Math.random().toString(36).slice(2, 11));

---

280-334: Guard async highlight against races; only set state if latest.

Rapid changes can set stale highlightedCode. Add a cancellation flag.

Apply this diff:

-  useEffect(() => {
+  useEffect(() => {
+    let cancelled = false;
@@
-        const sanitized = DOMPurify.sanitize(html, {
+        const sanitized = DOMPurify.sanitize(html, {
           KEEP_CONTENT: true,
         });
-        setHighlightedCode(sanitized);
+        if (!cancelled) setHighlightedCode(sanitized);
@@
-        setHighlightedCode(`<pre><code>${escapeHtml(currentCodeConfig.code)}</code></pre>`);
+        if (!cancelled) setHighlightedCode(`<pre><code>${escapeHtml(currentCodeConfig.code)}</code></pre>`);
@@
-    observer.observe(document.documentElement, {
+    observer.observe(document.documentElement, {
       attributes: true,
       attributeFilter: ['class']
     });
 
-    return () => observer.disconnect();
+    return () => {
+      cancelled = true;
+      observer.disconnect();
+    };
   }, [currentCodeConfig]);

---

407-411: Handle missing frameworks gracefully in label.

Avoid showing “undefined” when a platform has no frameworks.

Apply this diff:

-                <span>{currentFramework}</span>
+                <span>{currentFramework ?? 'No frameworks'}</span>

---

70-116: Prefer Map over plain objects for key–value collections.

selectedFrameworks/selectedVariants/globalSelectedFrameworks fit Map per guidelines; objects work but Maps avoid prototype pitfalls and ease deletion.

As per coding guidelines

Also applies to: 171-176

docs/src/components/mdx/simple-platform-codeblock.tsx (1)

56-82: Minor: consider Map for fullPlatforms to align with guidelines.

Objects are fine here, but Map would align with our Map-over-Record guidance and mirror PlatformCodeblock’s listener Maps.

As per coding guidelines

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

docs/src/mdx-components.tsx (1)

16-16: Importing a Client Component into the MDX registry is fine; consider lazy import to limit bundle size.

If PlatformCodeblock is rarely used, wrapping it in a dynamic import can keep the default MDX bundle lean. I can sketch a lazy wrapper if desired.

docs/src/components/mdx/platform-codeblock.tsx (6)

183-184: Use slice, not deprecated substr, and prefer crypto.randomUUID when available.

-  const [componentId] = useState(() => Math.random().toString(36).substr(2, 9));
+  const [componentId] = useState(
+    () => (typeof crypto !== 'undefined' && 'randomUUID' in crypto)
+      ? crypto.randomUUID()
+      : Math.random().toString(36).slice(2, 11),
+  );

---

27-33: Listener cleanup can leak empty arrays; delete keys when empty.

Free the map entry after removing the last listener.

 function removePlatformListener(id: string, listener: PlatformChangeListener): void {
   const list = platformListeners.get(id) ?? [];
-  platformListeners.set(
-    id,
-    list.filter((item) => item !== listener),
-  );
+  const next = list.filter((item) => item !== listener);
+  if (next.length === 0) platformListeners.delete(id);
+  else platformListeners.set(id, next);
 }
 
 function removeFrameworkListener(id: string, listener: FrameworkChangeListener): void {
   const list = frameworkListeners.get(id) ?? [];
-  frameworkListeners.set(
-    id,
-    list.filter((item) => item !== listener),
-  );
+  const next = list.filter((item) => item !== listener);
+  if (next.length === 0) frameworkListeners.delete(id);
+  else frameworkListeners.set(id, next);
 }

Also applies to: 41-47

---

332-343: Avoid UI flicker after platform selection by updating local state immediately.

Set local state before broadcasting so the Framework view shows the correct list right away.

 const handlePlatformSelect = (platform: string) => {
-  broadcastPlatformChange(platform);
-  // Show framework selection for this platform
-  setDropdownView('framework');
+  setSelectedPlatform(platform);
+  broadcastPlatformChange(platform);
+  setDropdownView('framework'); // now shows the right frameworks
 
   // Auto-select first framework of new platform
   const newPlatformFrameworks = Object.keys(platforms[platform] ?? {});
   if (newPlatformFrameworks.length > 0) {
     const firstFramework = defaultFrameworks[platform] || newPlatformFrameworks[0];
-    broadcastFrameworkChange(platform, firstFramework);
+    setSelectedFrameworks(prev => ({ ...prev, [platform]: firstFramework }));
+    broadcastFrameworkChange(platform, firstFramework);
   }
 };

---

450-456: dangerouslySetInnerHTML requires sanitization or a lint suppression.

If you adopt the sanitization above, this is resolved. Otherwise, add a documented eslint/biome suppression with justification.

---

413-437: Add basic a11y: ARIA attributes and roles for the dropdown.

Expose state to AT and use menu semantics.

 <div className="relative" data-dropdown-id={componentId}>
   <button
     onClick={handleDropdownToggle}
+    aria-haspopup="menu"
+    aria-expanded={isDropdownOpen}
+    aria-controls={`${componentId}-menu`}
 ...
 {isDropdownOpen && (
   <div
     className="absolute right-3 z-50 min-w-[160px] rounded-lg border bg-fd-background shadow-lg"
+    id={`${componentId}-menu`}
+    role="menu"
 ...
   {dropdownView === 'platform' ? (
-    <div className="py-1">
+    <div className="py-1" role="menu">
 ...
-              {platformNames.map((platform) => (
+              {platformNames.map((platform) => (
                 <button
                   key={platform}
+                  role="menuitem"
 ...
-    <div className="py-1">
+    <div className="py-1" role="menu">
 ...
-              {currentFrameworks.map((framework) => (
+              {currentFrameworks.map((framework) => (
                 <button
                   key={framework}
+                  role="menuitem"

Also applies to: 461-521

---

13-20: Consider Map over index signatures for dynamic key–value state.

globalSelectedFrameworks and selectedFrameworks model dictionaries; Map offers clearer intent and safer key handling. Convert only if cost is low; otherwise defer.

As per coding guidelines

Also applies to: 173-175

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

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

286-287: Avoid index as key in tree renders (same as prior review)

Use a deterministic key for non-page items to stabilize reconciliation. See earlier reviewer note.

-<PageTreeItem key={child.type === 'page' ? child.url : index} item={child} />
+<PageTreeItem key={child.type === 'page' ? child.url : `${child.type}-${typeof child.name === 'string' ? child.name : index}` } item={child} />

-<PageTreeItem key={item.type === 'page' ? item.url : index} item={item} />
+<PageTreeItem key={item.type === 'page' ? item.url : `${item.type}-${typeof item.name === 'string' ? item.name : index}` } item={item} />

Also applies to: 299-300, 321-322

docs/src/components/api/auth-panel.tsx (2)

75-76: Simplify dead conditional and clarify height intent.

Line 75 has a no-op ternary (both branches return 'top-0'), which should be simplified to a constant assignment. Line 76's height calculation also uses nearly identical values ('h-screen' vs 'h-[calc(100vh)]') that behave identically in most viewport scenarios.

Apply this diff to simplify:

-  const topPosition = isHomePage && isScrolled ? 'top-0' : 'top-0';
-  const height = isHomePage && isScrolled ? 'h-screen' : 'h-[calc(100vh)]';
+  const topPosition = 'top-0';
+  const height = 'h-screen';

If the distinction between h-screen and h-[calc(100vh)] is meaningful for handling mobile browser chrome behavior, document the rationale in a comment. Otherwise, consolidate to a single value.

---

41-72: Consider removing unused state observation.

Given that topPosition is now constant and height has minimal variation, the isHomePage and isScrolled state tracking (and the associated MutationObserver) may no longer serve a purpose. If these states aren't used elsewhere or the height distinction isn't critical, removing this complexity would improve maintainability.

If you decide to keep the distinction, ensure the state is actually necessary. Otherwise, remove the observer setup:

-  const [isHomePage, setIsHomePage] = useState(false);
-  const [isScrolled, setIsScrolled] = useState(false);
-
-  // Detect if we're on homepage and scroll state (same as AIChatDrawer)
-  useEffect(() => {
-    const checkHomePage = () => {
-      setIsHomePage(document.body.classList.contains('home-page'));
-    };
-
-    const checkScrolled = () => {
-      setIsScrolled(document.body.classList.contains('scrolled'));
-    };
-
-    // Initial check
-    checkHomePage();
-    checkScrolled();
-
-    // Set up observers for class changes
-    const observer = new MutationObserver(() => {
-      checkHomePage();
-      checkScrolled();
-    });
-
-    observer.observe(document.body, {
-      attributes: true,
-      attributeFilter: ['class']
-    });
-
-    return () => {
-      observer.disconnect();
-    };
-  }, []);

docs/src/components/layout/toc.tsx (1)

42-73: Consider removing unused state tracking.

Since both topPosition and height now resolve to constant values regardless of isHomePage and isScrolled, the entire state tracking mechanism (including the MutationObserver) is unused and adds unnecessary runtime overhead.

If the simplified positioning is intentional, apply this diff to remove the unused code:

-  // State for tracking homepage and scroll detection (similar to AI Chat)
-  const [isHomePage, setIsHomePage] = useState(false);
-  const [isScrolled, setIsScrolled] = useState(false);
-
-  // Detect if we're on homepage and scroll state
-  useEffect(() => {
-    const checkHomePage = () => {
-      setIsHomePage(document.body.classList.contains('home-page'));
-    };
-
-    const checkScrolled = () => {
-      setIsScrolled(document.body.classList.contains('scrolled'));
-    };
-
-    // Initial check
-    checkHomePage();
-    checkScrolled();
-
-    // Set up observers for class changes
-    const observer = new MutationObserver(() => {
-      checkHomePage();
-      checkScrolled();
-    });
-
-    observer.observe(document.body, {
-      attributes: true,
-      attributeFilter: ['class']
-    });
-
-    return () => {
-      observer.disconnect();
-    };
-  }, []);
-
-  // Calculate position based on homepage and scroll state (same as AI Chat and Auth Panel)
-  const topPosition = 'top-0';
-  const height = 'h-screen';

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

242-273: Add aria-label for better accessibility.

The trigger button looks good, but should include an aria-label attribute for screen readers, as title attributes are not consistently announced.

Apply this diff:

     <button
       onClick={onClick}
       className={cn(
         "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-200",
         "border border-fd-primary/20"
       )}
       style={{
         left: '50%',
         transform: 'translateX(-50%)'
       }}
       title="View Code Example"
+      aria-label="View Code Example"
     >

docs/src/components/layouts/api/api-sidebar.tsx (1)

68-69: Consider ES6 Map over Record for key-value collections.

Multiple locations use Record<string, ...> for runtime key-value collections:

• Line 68: groups: Record<string, OrganizedGroup>
• Line 85-92: accordionState: Record<string, boolean>

As per coding guidelines, prefer ES6 Map for dynamic key-value collections as it provides better type safety, avoids prototype pollution, and offers a cleaner API for runtime operations.

Example for accordion state:

-type AccordionContextType = {
-  accordionState: Record<string, boolean>,
-  setAccordionState: (key: string, isOpen: boolean) => void,
-}
+type AccordionContextType = {
+  accordionState: Map<string, boolean>,
+  setAccordionState: (key: string, isOpen: boolean) => void,
+}

 function AccordionProvider({ children }: { children: ReactNode }) {
-  const [accordionState, setAccordionStateInternal] = useState<Record<string, boolean>>({});
+  const [accordionState, setAccordionStateInternal] = useState<Map<string, boolean>>(new Map());

   const setAccordionState = (key: string, isOpen: boolean) => {
-    setAccordionStateInternal(prev => ({ ...prev, [key]: isOpen }));
+    setAccordionStateInternal(prev => new Map(prev).set(key, isOpen));
   };

Based on coding guidelines.

Also applies to: 85-92

docs/src/app/global.css (3)

33-39: Deduplicate transition rules for #nd-docs-layout and #api-main-content

Same transition declared twice; keep one to avoid override churn.

 /* Default transitions for main content */
-#nd-docs-layout {
-  transition: margin-left 300ms ease-out;
-}
-
-#api-main-content {
-  transition: margin-left 300ms ease-out;
-}
+/* (kept above at lines ~33 and ~37) */

Also applies to: 47-53

---

17-19: Anchor offset likely mismatched with header height on lg screens

[id]{ scroll-margin-top: 7rem } (112px) while header is h-14 (56px) on small and intended ~6.5rem (104px) on lg. Use a CSS var responsive to breakpoints to prevent awkward extra gap.

-:root {
-  --color-fd-background: #fafbfd;
-}
+:root {
+  --color-fd-background: #fafbfd;
+  --nd-header-offset: 3.5rem; /* h-14 */
+}
+.dark {
   --color-fd-background: hsl(0, 0%, 7.04%);
 }
+[id] { scroll-margin-top: var(--nd-header-offset); }
+@media (min-width: 1024px) {
+  :root { --nd-header-offset: 6.5rem; } /* matches lg header height */
+}
-
-[id] {
-  scroll-margin-top: 7rem;
-}

Also applies to: 263-266

---

145-196: Respect prefers-reduced-motion for heavy, infinite animations

Add a motion-reduced override to cut CPU/GPU cost and improve a11y.

 @keyframes gradient-shift { ... }
 @keyframes gradient-noise { ... }
 .chat-gradient-active::before { ... }
+@media (prefers-reduced-motion: reduce) {
+  .chat-gradient-active::before {
+    animation: none !important;
+  }
+  #nd-docs-layout, #api-main-content, .api-sidebar, body:not(.home-page) {
+    transition: none !important;
+  }
+}

docs/src/components/layouts/shared-header.tsx (3)

73-95: Make className optional on toggle components

Loosen prop typing; avoid forcing callers to pass a string.

-function AIChatToggleButton(props: { className: string }) {
+function AIChatToggleButton({ className = '' }: { className?: string }) {
 ...
-        props.className,
+        className,
 ...
-function TOCToggleButtonInner(props: { className: string }) {
+function TOCToggleButtonInner({ className = '' }: { className?: string }) {
 ...
-          : 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50',
-        props.className
+          : 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50',
+        className
 ...
-function TOCToggleButton(props: { className: string }) {
+function TOCToggleButton(props: { className?: string }) {
 ...
-function AuthToggleButton(props: { className: string }) {
+function AuthToggleButton({ className = '' }: { className?: string }) {
 ...
-          : 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50',
-        props.className
+          : 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50',
+        className

Also applies to: 101-133, 138-147, 152-183

---

322-345: Use stable keys for nav items (avoid array index)

Prevents reconciliation glitches when links change.

-  {navLinks.map((link, index) => {
+  {navLinks.map((link) => {
 ...
-    <Link key={index} href={link.href} ...
+    <Link key={link.href ?? link.label} href={link.href} ...

-  {navLinks.map((link, index) => {
+  {navLinks.map((link) => {
 ...
-    <Link key={index} href={link.href} ...
+    <Link key={link.href ?? link.label} href={link.href} ...

Also applies to: 366-385

---

293-299: Comment mismatch: Auth toggle only shows on API pages

Comment says “shows on all pages,” but component gates on isInApiSection. Update comment to avoid confusion.

-/* Auth Toggle Button - Shows on all pages like AI Chat button */
+/* Auth Toggle Button - Only on API pages */

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

86-99: Use ES6 Map for accordion state (per guidelines)

Improves semantics and avoids accidental key collisions. Also aligns with repo guideline to prefer Map over Record for key–value collections.
[Based on coding guidelines]

-type AccordionContextType = {
-  accordionState: Record<string, boolean>,
-  setAccordionState: (key: string, isOpen: boolean) => void,
-};
+type AccordionContextType = {
+  accordionState: Map<string, boolean>,
+  setAccordionState: (key: string, isOpen: boolean) => void,
+};

 function AccordionProvider({ children }: { children: ReactNode }) {
-  const [accordionState, setAccordionStateInternal] = useState<Record<string, boolean>>({});
+  const [accordionState, setAccordionStateInternal] = useState<Map<string, boolean>>(
+    () => new Map<string, boolean>()
+  );

   const setAccordionState = (key: string, isOpen: boolean) => {
-    setAccordionStateInternal(prev => ({ ...prev, [key]: isOpen }));
+    setAccordionStateInternal(prev => {
+      const next = new Map(prev);
+      next.set(key, isOpen);
+      return next;
+    });
   };

 function useAccordionState(key: string, defaultValue: boolean) {
 ...
-  const isOpen = accordionState[key] ?? defaultValue;
+  const isOpen = accordionState.get(key) ?? defaultValue;

Also applies to: 106-120

---

344-345: Hard-coded blue; tie dot color to theme token

Use the design token to respect theming and reduce magic numbers.

-const platformColor = 'rgb(59, 130, 246)';
+const platformColor = 'hsl(var(--fd-primary))';

And where translucency is needed, prefer modern syntax:

- backgroundColor: isCurrentlyActive ? platformColor : 'rgb(100, 116, 139)',
+ backgroundColor: isCurrentlyActive ? platformColor : 'hsl(var(--fd-primary) / 0.4)',

Similarly replace ${platformColor}40 with hsl(var(--fd-primary) / 0.25), and borders with 1px solid hsl(var(--fd-primary)).

Also applies to: 445-446, 600-601

---

354-355: Prefer Link for navigation to preserve prefetch and accessibility

Using router.push inside buttons drops prefetch and default a11y affordances. Wrap the dot with a Link or render an anchor styled as a dot.

-<button onClick={handleNavigation} ...>
+<Link href={href} onClick={(e) => { setIsOpen?.(true); }} role="button" aria-label={`Go to ${title}`}>
   ...
-</button>
+</Link>

Also applies to: 456-457

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

diff --git a/docs/src/components/layouts/shared-header.tsx b/docs/src/components/layouts/shared-header.tsx
index 387c1e82..04cbefb0 100644
--- a/docs/src/components/layouts/shared-header.tsx
+++ b/docs/src/components/layouts/shared-header.tsx
@@ -260,7 +260,7 @@ export function SharedHeader({
 
   return (
     <>
-      <header className="sticky top-0 w-full h-14 lg:h-26 z-49 flex flex-col space-around bg-fd-background">
+      <header className="sticky top-0 w-full h-14 lg:h-26 z-50 flex flex-col space-around bg-fd-background">
 
         {/* First row */}
         <div className="flex items-center justify-between h-14 border-b border-fd-border px-4">

Analysis

Invalid Tailwind CSS z-index class z-49 in header component

What fails: SharedHeader component in docs/src/components/layouts/shared-header.tsx line 263 uses z-49 which is not a standard Tailwind CSS utility class

How to reproduce:

cd docs && grep -n "z-49" src/components/layouts/shared-header.tsx

Result: Shows z-49 class on line 263. Standard Tailwind CSS z-index utilities are: z-0, z-10, z-20, z-30, z-40, z-50, z-auto per official documentation

Expected: Should use z-50 (next standard value) or z-[49] (arbitrary value syntax) for proper z-index styling

diff --git a/docs/src/components/layouts/shared-header.tsx b/docs/src/components/layouts/shared-header.tsx
index 387c1e82..96b2f84c 100644
--- a/docs/src/components/layouts/shared-header.tsx
+++ b/docs/src/components/layouts/shared-header.tsx
@@ -260,7 +260,7 @@ export function SharedHeader({
 
   return (
     <>
-      <header className="sticky top-0 w-full h-14 lg:h-26 z-49 flex flex-col space-around bg-fd-background">
+      <header className="sticky top-0 w-full h-14 lg:h-28 z-49 flex flex-col space-around bg-fd-background">
 
         {/* First row */}
         <div className="flex items-center justify-between h-14 border-b border-fd-border px-4">

Analysis

Invalid Tailwind CSS class lg:h-26 in SharedHeader component

What fails: SharedHeader component in docs/src/components/layouts/shared-header.tsx line 263 uses lg:h-26 which is not a valid Tailwind CSS utility class

How to reproduce:

# The class is present in the header component:
grep -n "lg:h-26" docs/src/components/layouts/shared-header.tsx

Result: Class lg:h-26 found at line 263 but Tailwind CSS default spacing scale jumps from h-24 (6rem) to h-28 (7rem), with no h-26 (6.5rem) utility available

Expected: Should use a valid Tailwind height class like lg:h-24 or lg:h-28, or implement a custom height utility if 6.5rem is specifically needed per Tailwind CSS height documentation

diff --git a/docs/src/components/mdx/platform-codeblock.tsx b/docs/src/components/mdx/platform-codeblock.tsx
index d0e4db75..237535b4 100644
--- a/docs/src/components/mdx/platform-codeblock.tsx
+++ b/docs/src/components/mdx/platform-codeblock.tsx
@@ -240,6 +240,8 @@ export function PlatformCodeblock({
     });
   }, [platformNames, platforms, defaultFrameworks]);
 
+  const [selectedPlatform, setSelectedPlatform] = useState(getInitialPlatform);
+
   // Initialize global state on first render
   useEffect(() => {
     initializeGlobalFrameworks();
@@ -251,8 +253,6 @@ export function PlatformCodeblock({
       }
     }
   }, [initializeGlobalFrameworks, platformNames]);
-
-  const [selectedPlatform, setSelectedPlatform] = useState(getInitialPlatform);
   const [selectedFrameworks, setSelectedFrameworks] = useState<{ [platform: string]: string }>(() => {
     // Don't initialize with defaults - let users manually select frameworks
     return { ...globalSelectedFrameworks };

Analysis

ReferenceError in PlatformCodeblock component due to useState called after useEffect

What fails: PlatformCodeblock.useEffect() on line 244 calls setSelectedPlatform() before the useState declaration on line 255, causing a Temporal Dead Zone violation

How to reproduce:

1. Load any page using PlatformCodeblock component
2. Component initialization triggers useEffect before useState
3. Results in "Cannot access 'setSelectedPlatform' before initialization" ReferenceError

Result: Component crashes during initialization when setSelectedPlatform(storedPlatform) is called at line 250

Expected: useState should be declared before any useEffect that references its setter function, per JavaScript Temporal Dead Zone rules

diff --git a/docs/src/lib/docs-tree.ts b/docs/src/lib/docs-tree.ts
index 8719dbcb..8eb053e7 100644
--- a/docs/src/lib/docs-tree.ts
+++ b/docs/src/lib/docs-tree.ts
@@ -101,7 +101,7 @@ function matchesSection(url: string, section: DocsSection): boolean {
 }
 
 function normalizeUrl(url: string): string {
-  const withoutFragment = url.split('#')[0] ?? throwErr("URL split by # returned empty array", { url });
+  const withoutFragment = url.split('#')[0];
   return withoutFragment.replace(/\/$/, '');
 }
 

Analysis

Dead code in normalizeUrl() - throwErr will never execute

What fails: The normalizeUrl() function in docs/src/lib/docs-tree.ts:104 uses url.split('#')[0] ?? throwErr(...) but the throwErr will never execute because split('#')[0] cannot return null or undefined

How to reproduce:

// String.prototype.split() always returns a non-empty array
console.log(''.split('#')); // ['']
console.log('#fragment'.split('#')); // ['', 'fragment']  
console.log('path#fragment'.split('#')); // ['path', 'fragment']
// Accessing [0] always returns a string (possibly empty), never null/undefined

Result: Dead code with misleading error message "URL split by # returned empty array" that can never be triggered

Expected: Per MDN documentation, split() always returns an array, so accessing [0] always returns a string value

docs/content/docs/sdk/types/user.mdx (1)

1321-1323: Fix ServerUser contact channel types in TOC.

The table of contents (line 1321–1323) shows ContactChannel[], but server-side contact channels should be typed as ServerContactChannel[].

-      listContactChannels(): Promise<ContactChannel[]>; //$stack-link-to:#serveruserlistcontactchannels
-      // NEXT_LINE_PLATFORM react-like
-      ⤷ useContactChannels(): ContactChannel[]; //$stack-link-to:#serveruserusecontactchannels
+      listContactChannels(): Promise<ServerContactChannel[]>; //$stack-link-to:#serveruserlistcontactchannels
+      // NEXT_LINE_PLATFORM react-like
+      ⤷ useContactChannels(): ServerContactChannel[]; //$stack-link-to:#serveruserusecontactchannels

docs/content/docs/sdk/types/team.mdx (1)

612-612: Update client-vs-server link to guides path.

Line 612 references the old ../../concepts/stack-app.mdx path. Update to the new guides structure introduced in this PR refactor.

-Like [`Team`](#team), but with [server permissions](../../concepts/stack-app.mdx#client-vs-server). Has full read and write access to everything.
+Like [`Team`](#team), but with [server permissions](/docs/guides/concepts/stack-app#client-vs-server). Has full read and write access to everything.

docs/src/components/mdx/platform-codeblock.tsx (2)

156-162: Default variant should be the first provided, not always 'server'.

This incorrectly picks server even when only a client variant exists.

Apply this diff:

-      // Initialize default variants
+      // Initialize default variants to the first provided (server or client)
       if (!(language in defaultVariants)) {
         defaultVariants[language] = {};
       }
       if (!defaultVariants[language]?.[framework]) {
-        defaultVariants[language]![framework] = 'server';
+        defaultVariants[language]![framework] = variantType;
       }

---

277-280: Validate persisted framework before use to avoid empty code panes.

A stale selectedFrameworks[selectedPlatform] can be invalid for the current platform, yielding no content.

Apply this diff:

-  const currentFramework = selectedFrameworks[selectedPlatform] || currentFrameworks[0];
+  const selected = selectedFrameworks[selectedPlatform];
+  const currentFramework = (selected && currentFrameworks.includes(selected))
+    ? selected
+    : currentFrameworks[0];

docs/src/app/layout.tsx (1)

18-18: Clarify the need for suppressHydrationWarning on body.

The suppressHydrationWarning attribute has been added to the <body> element. While this suppresses hydration mismatch warnings, it's generally preferable to identify and fix the root cause of hydration differences between server and client rendering.

Could you clarify what specific hydration issue this is addressing? Common sources in this layout might include:

• Dynamic theme classes from StackTheme
• Third-party scripts injected by PostHogProvider
• Client-side state from RootProvider

If there's a specific, intentional mismatch (e.g., theme persistence), consider adding a comment explaining why this suppression is necessary.

docs/content/docs/(guides)/others/convex.mdx (3)

52-56: Clarify that the three client setup approaches are mutually exclusive.

Presenting all three options (convexClient, convexReactClient, convexHttpClient) in a single code block may suggest they should all be used together. Add a clarifying comment or restructure to show that only one applies per context.

Consider updating the code block:

 Then, update your Convex client to use Stack Auth:

 ```ts
-convexClient.setAuth(stackServerApp.getConvexClientAuth({}));  // browser JS
-convexReactClient.setAuth(stackServerApp.getConvexClientAuth({}));  // React
-convexHttpClient.setAuth(stackServerApp.getAuthForConvexHttpClient({ tokenStore: requestObject }));  // HTTP, see Stack Auth docs for more information on tokenStore
+// Choose ONE of the following based on your context:
+
+convexClient.setAuth(stackServerApp.getConvexClientAuth({}));  // browser JS
+// OR
+convexReactClient.setAuth(stackServerApp.getConvexClientAuth({}));  // React
+// OR
+convexHttpClient.setAuth(stackServerApp.getAuthForConvexHttpClient({ tokenStore: requestObject }));  // HTTP client

---

`45-45`: **Clarify environment variable choice.**

Line 45 presents two possible environment variables (`STACK_PROJECT_ID` or `NEXT_PUBLIC_STACK_PROJECT_ID`) but doesn't explain when to use each. The comment suggests either works, which may confuse users about security/exposure implications.

Enhance the comment to clarify the choice:

```diff
-    projectId: process.env.STACK_PROJECT_ID,  // or: process.env.NEXT_PUBLIC_STACK_PROJECT_ID
+    projectId: process.env.STACK_PROJECT_ID || process.env.NEXT_PUBLIC_STACK_PROJECT_ID,  // Use STACK_PROJECT_ID on server, NEXT_PUBLIC_STACK_PROJECT_ID if client-side access needed

---

55-55: Provide direct link for tokenStore documentation.

Line 55 references "see Stack Auth docs for more information on tokenStore" but uses a vague reference. Include a direct link or more specific guidance for clarity.

Update the comment with a more specific reference:

-convexHttpClient.setAuth(stackServerApp.getAuthForConvexHttpClient({ tokenStore: requestObject }));  // HTTP, see Stack Auth docs for more information on tokenStore
+convexHttpClient.setAuth(stackServerApp.getAuthForConvexHttpClient({ tokenStore: requestObject }));  // HTTP; for tokenStore details, see https://docs.stack-auth.com/sdk/token-storage

docs/content/docs/sdk/types/team.mdx (1)

780-787: Move example section to proper AsideSection wrapper.

Line 782–787 places ### Examples and code block directly inside an <AsideSection> as Markdown, instead of wrapping them in a sibling <AsideSection title="Examples"> component. This breaks consistency with other method sections.

     <MethodAside>
       <AsideSection title="Signature">

         ```typescript
         declare function removeUser(userId: string): Promise<void>;
         ```
-      ### Examples
-
+      </AsideSection>
+      <AsideSection title="Examples">
         ```typescript Removing a user from the team
         await team.removeUser('user_id_123');
         ```
       </AsideSection>
     </MethodAside>

docs/src/components/mdx/base-codeblock.tsx (3)

67-70: Make theme detection resilient; avoid per‑instance observers.

Matching a specific CSS var value is brittle. Prefer a clear signal (html.dark or data-theme) and centralize theme change notifications to avoid N MutationObservers (one per block).

Example refactor:

+function getThemeFromDom(): 'github-dark' | 'github-light' {
+  const root = document.documentElement;
+  const dark = root.classList.contains('dark') || root.getAttribute('data-theme') === 'dark';
+  return dark ? 'github-dark' : 'github-light';
+}
...
-          const isDarkMode = document.documentElement.classList.contains('dark') ||
-                            getComputedStyle(document.documentElement).getPropertyValue('--fd-background').includes('0 0% 3.9%');
-          theme = isDarkMode ? 'github-dark' : 'github-light';
+          theme = getThemeFromDom();
...
-    const observer = new MutationObserver(() => {
-      runAsynchronously(updateHighlightedCode);
-    });
-    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
-    return () => observer.disconnect();
+    // Prefer a shared ThemeContext or a window event 'docs:theme-change'
+    window.addEventListener('docs:theme-change', updateHighlightedCode);
+    return () => window.removeEventListener('docs:theme-change', updateHighlightedCode);

If a shared context/event isn’t available yet, keep one observer at the app shell and dispatch the event.

Also applies to: 112-118

---

72-75: Normalize code input predictably.

Removing only a single leading space is fragile. Normalize leading newline/indent consistently so highlighting output is stable.

Example:

-        const codeToHighlight = code.startsWith(' ')
-          ? code.slice(1)
-          : code;
+        const codeToHighlight = code.replace(/^\n/, ''); // drop a single leading newline from MDX fences

Or introduce a tiny helper to strip common indentation (dedent) without altering meaningful leading spaces.

Also applies to: 100-101

---

107-115: Many code blocks = many observers; consider centralizing.

Each BaseCodeblock attaches a MutationObserver. On pages with many blocks this adds overhead.

Expose a context/provider that emits theme changes once; BaseCodeblock subscribes via an event or context value (you already have themeKey — leverage it).

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

66-76: Gate auto‑open behind a prop; avoid surprising users.

Auto‑opening the overlay on mount can be intrusive, especially on mobile or pages with multiple code blocks.

Apply this diff to make it opt‑in:

 type DynamicCodeblockProps = {
   code: string,
   language?: string,
   title?: string,
+  autoOpen?: boolean,
 }
...
 export function DynamicCodeblock({
   code,
   language = 'tsx',
-  title = "Code Example"
+  title = "Code Example",
+  autoOpen = false,
 }: DynamicCodeblockProps) {
...
-  if (code && !hasInitialized) {
+  if (autoOpen && code && !hasInitialized) {

---

85-113: Add button type and accessible label; respect reduced motion.

Improve a11y and motion sensitivity.

-      <button
+      <button
+        type="button"
         onClick={() => openOverlay(code, language, title)}
         className={cn(
           "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",
+          "hover:scale-105 active:scale-95",
+          "transition-all duration-300 motion-reduce:transition-none motion-reduce:hover:transform-none",
           "border border-fd-primary/20"
         )}
...
-        title="View Code Example"
+        title="View Code Example"
+        aria-label="View code example"
       >

docs/src/components/mdx/sdk-components.tsx (3)

28-99: Re‑measure line positions on theme change (fonts/metrics can shift).

Current effect runs on code changes, timeouts, and resize. Theme flips can alter line-height, desyncing overlays.

If you already emit a themeKey (BaseCodeblock supports it), pass it down and include it in dependencies:

 function ClickableCodeblock({ ... , title }: { ... }) {
   ...
-  useEffect(() => {
+  useEffect(() => {
     if (codeRef.current) {
       const measurePositions = () => { /* ... */ };
       measurePositions();
       const timeoutId1 = setTimeout(measurePositions, 100);
       const timeoutId2 = setTimeout(measurePositions, 300);
       const handleResize = () => measurePositions();
       window.addEventListener('resize', handleResize);
       return () => { /* cleanup */ };
     }
-  }, [code]);
+  }, [code, /* themeKey */]);

Alternatively, subscribe to a central “docs:theme-change” event and call measurePositions().

---

389-407: Avoid O(n²) mapping for clickableAreas.

Using findIndex over processedLines for each clickable item is quadratic. Track the rendered line index during the initial map.

Sketch:

const processedLines = [];
for (let i = 0; i < lines.length; i++) {
  // build item; push to processedLines
}
const clickableAreas = processedLines
  .map((item, idx) => ({ item, idx }))
  .filter(({ item }) => item.type === 'clickable')
  .map(({ item, idx }) => ({
    type: 'clickable' as const,
    code: item.code,
    anchor: item.anchor,
    lineNumber: idx,
    originalLineNumber: item.originalLineIndex,
  }));

---

167-258: Prefer Map over Record for key–value collections.

The snippetContent table is a collection; using Map improves semantics and iteration guarantees. As per coding guidelines.

Example diff:

-  const snippetContent: Record<string, () => React.ReactElement> = {
-    '../../snippets/stack-app-constructor-options-before-ssk.mdx': () => (/* ... */),
-    '../../snippets/stack-app-constructor-options-after-ssk.mdx': () => (/* ... */),
-  };
+  const snippetContent = new Map<string, () => React.ReactElement>([
+    ['../../snippets/stack-app-constructor-options-before-ssk.mdx', () => (/* ... */)],
+    ['../../snippets/stack-app-constructor-options-after-ssk.mdx', () => (/* ... */)],
+  ]);
...
-  const ContentComponent = snippetContent[src];
-  if (!(src in snippetContent)) {
+  const ContentComponent = snippetContent.get(src);
+  if (!ContentComponent) {
     console.warn(`Snippet not found: ${src}`);
     return <div className="markdown-include text-red-500">Snippet not found: {src}</div>;
   }
-  return <ContentComponent />;
+  return <ContentComponent />;

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

75-125: DRY the highlight logic with BaseCodeblock.

This duplicates BaseCodeblock’s Shiki + theme logic. Extract a shared helper/hook (e.g., useShikiHighlight(code, language)) or a module-level function that returns sanitized HTML. Reduces bugs and keeps theming consistent.

I can factor this into a small hook used by both components.

---

201-233: Button a11y and form‑safety.

Add type="button" to buttons to avoid implicit submit, and add aria-live for the “Copied!” feedback.

-            <button
+            <button
+              type="button"
               onClick={() => runAsynchronously(() => handleCopy())}
...
-            <button
+            <button
+              type="button"
               onClick={() => setIsExpanded(!isExpanded)}
...
-            <button
+            <button
+              type="button"
               onClick={() => onToggle?.(false)}

Add an offscreen live region near the buttons:

+          <span aria-live="polite" className="sr-only">
+            {copied ? 'Code copied to clipboard' : ''}
+          </span>

---

75-105: Reuse a singleton Shiki highlighter for performance.

Creating a highlighter per call is expensive. Cache a highlighter instance and reuse across renders.

I can wire a module-level getHighlighterSingleton() and swap codeToHtml for highlighter.codeToHtml(theme). Based on learnings.

docs/src/mdx-components.tsx (1)

29-29: Type‑safe MDX img mapping; drop any‑cast.

Avoid any and the lint suppression. You can derive the correct prop type from MDXComponents['img'].

Apply this diff:

   JWTViewer,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  img: (props) => <ImageZoom {...(props as any)} />,
+  // Type-safe: reuse MDX's img prop type
+  img: (props: Parameters<NonNullable<MDXComponents['img']>>[0]) => <ImageZoom {...props} />,

Also applies to: 93-95

docs/src/components/mdx/platform-codeblock.tsx (5)

27-33: Clean up listener maps when empty to avoid leaks.

After removing the last listener, delete the key from the Map.

Apply this diff:

 function removePlatformListener(id: string, listener: PlatformChangeListener): void {
   const list = platformListeners.get(id) ?? [];
-  platformListeners.set(
-    id,
-    list.filter((item) => item !== listener),
-  );
+  const next = list.filter((item) => item !== listener);
+  if (next.length) platformListeners.set(id, next);
+  else platformListeners.delete(id);
 }
 
 function removeFrameworkListener(id: string, listener: FrameworkChangeListener): void {
   const list = frameworkListeners.get(id) ?? [];
-  frameworkListeners.set(
-    id,
-    list.filter((item) => item !== listener),
-  );
+  const next = list.filter((item) => item !== listener);
+  if (next.length) frameworkListeners.set(id, next);
+  else frameworkListeners.delete(id);
 }

Also applies to: 41-47

---

214-241: Sanitize and validate restored frameworks from sessionStorage.

Merge only entries that exist in platforms and whose framework is valid for that platform to prevent inconsistent state.

Apply this diff:

   if (typeof window !== 'undefined') {
     const stored = sessionStorage.getItem('stack-docs-selected-frameworks');
     if (stored) {
       try {
-        const parsed = JSON.parse(stored);
-        globalSelectedFrameworks = { ...globalSelectedFrameworks, ...parsed };
+        const parsed = JSON.parse(stored) as Record<string, string>;
+        const valid: Record<string, string> = {};
+        for (const [plat, fw] of Object.entries(parsed)) {
+          if (platformNames.includes(plat)) {
+            const available = Object.keys(platforms[plat] ?? {});
+            if (available.includes(fw)) valid[plat] = fw;
+          }
+        }
+        globalSelectedFrameworks = { ...globalSelectedFrameworks, ...valid };
       } catch (e) {
         // Ignore parsing errors
       }
     }
   }

---

282-291: Simplify hasVariants (optional).

The typeof config !== 'object' guard is redundant. Directly probe keys on a safe fallback.

Apply this diff:

-  const hasVariants = (platform: string, framework: string) => {
-    const platformConfig = platforms[platform];
-    const config = platformConfig[framework];
-    if (typeof config !== 'object') {
-      return false;
-    }
-
-    return 'server' in config && 'client' in config;
-  };
+  const hasVariants = (platform: string, framework: string) => {
+    const config = platforms[platform]?.[framework] ?? {};
+    return 'server' in (config as object) && 'client' in (config as object);
+  };

---

416-433: Add basic ARIA to the dropdown trigger (optional).

Improve accessibility by indicating popup state.

Apply this diff:

-            <button
-              onClick={toggleDropdown}
+            <button
+              onClick={toggleDropdown}
+              aria-haspopup="listbox"
+              aria-expanded={isDropdownOpen}
+              aria-controls={`pc-menu-${componentId}`}
               className={cn(

And set the menu container id:

-              <div className="absolute right-0 top-full z-[200] mt-1 min-w-[220px] rounded-lg border border-fd-border/70 bg-fd-background shadow-lg">
+              <div
+                id={`pc-menu-${componentId}`}
+                role="listbox"
+                className="absolute right-0 top-full z-[200] mt-1 min-w-[220px] rounded-lg border border-fd-border/70 bg-fd-background shadow-lg"
+              >

---

117-121: Consider Map over Record for key–value collections (defer).

defaultFrameworks, selectedFrameworks, and selectedVariants model maps; using Map can clarify intent and avoid prototype pitfalls. This is optional given the current state management.

As per coding guidelines

Also applies to: 255-261

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: N2D4
PR: stack-auth/stack-auth#943
File: examples/convex/app/action/page.tsx:23-28
Timestamp: 2025-10-11T04:13:19.308Z
Learning: In the stack-auth codebase, use `runAsynchronouslyWithAlert` from `stackframe/stack-shared/dist/utils/promises` for async button click handlers and form submissions instead of manual try/catch blocks. This utility automatically handles errors and shows alerts to users.