perf(website): Defer Demo playground hydration without SSG code loss (#4030)

* perf(website): Mount only the selected Demo playground

Avoid hydrating Monaco and DataProvider for every protocol tab on the
homepage. Align CodeProvider tab sync with Docusaurus and fix
useTabStorage double-prefixing localStorage keys.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(website): Keep Demo protocols mounted for SSG, defer hydration

Restore mounting all protocol sandboxes so open-file source stays in
static HTML for crawlers. Skip LivePreview while hidden and latch Monaco
hydration on first show so inactive protocols stay cheap without losing
editor state after a visit.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ntucker

website/src/components/Demo/CodeEditor.tsx

@@ -48,7 +48,7 @@ const DemoPlayground = memo(
                   title={capitalizeFirstLetter(path)}
                   path={`${value}/${path}.tsx`}
                   collapsed={!open}
-                  autoFocus={autoFocus && Object.values(code).length === i + 1}
+                  autoFocus={autoFocus && code.length === i + 1}
                 >
                   {instanceCode}
                 </PlaygroundCode>

website/src/components/Demo/CodeProvider.tsx

@@ -1,4 +1,5 @@
 import { useScrollPositionBlocker } from '@docusaurus/theme-common/internal';
+import useIsomorphicLayoutEffect from '@docusaurus/useIsomorphicLayoutEffect';
 import React, { memo, useState } from 'react';
 
 import CodeTabContext from './CodeTabContext';
@@ -27,39 +28,32 @@ export function CodeProvider<V extends CodeTabValue[]>({
   playgroundRef,
   children,
 }: Props<V>) {
-  const [choice, setTabGroupChoice] = useTabStorage(
-    `docusaurus.tab.${groupId}`,
-  );
-  const [selectedValue, setLocalSelectedValue] = useState(defaultValue);
+  const [choice, setTabGroupChoice] = useTabStorage(groupId);
+  const [selectedValue, setSelectedValue] = useState(defaultValue);
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
 
-  if (
-    choice != null &&
-    choice !== selectedValue &&
-    isTabValue(values, choice)
-  ) {
-    setLocalSelectedValue(choice);
-  }
-
-  const setSelectedValue = (newTabValue: string) => {
-    if (newTabValue !== selectedValue) {
-      const el = playgroundRef.current;
-      if (el) {
-        blockElementScrollPositionUntilNextRender(el);
-      }
-      setLocalSelectedValue(newTabValue as V[number]['value']);
-
-      if (groupId != null) {
-        setTabGroupChoice(newTabValue);
-      }
+  // Local state stays interactive if storage no-ops; sync like Docusaurus tabs.
+  useIsomorphicLayoutEffect(() => {
+    if (choice != null && isTabValue(values, choice)) {
+      setSelectedValue(choice);
     }
-  };
+  }, [choice, values]);
 
   const value = {
     selectedValue,
     values,
-    setSelectedValue,
+    setSelectedValue: (newTabValue: string) => {
+      if (!isTabValue(values, newTabValue) || newTabValue === selectedValue) {
+        return;
+      }
+      const el = playgroundRef.current;
+      if (el) {
+        blockElementScrollPositionUntilNextRender(el);
+      }
+      setSelectedValue(newTabValue);
+      setTabGroupChoice(newTabValue);
+    },
   };
   return (
     <CodeTabContext.Provider value={value}>{children}</CodeTabContext.Provider>

website/src/components/HooksPlayground.tsx

@@ -35,17 +35,14 @@ const HooksPlayground = ({
 );
 export default memo(HooksPlayground);
 
-//child.props.children.props.title
-
 interface PlaygroundProps<T = any> {
   groupId: string;
   defaultOpen?: 'y' | 'n';
   row: boolean;
-  hidden: boolean;
+  hidden?: boolean;
   fixtures?: (Fixture | Interceptor<T>)[];
   getInitialInterceptorData?: () => T;
   children: React.ReactNode;
-  reverse?: boolean;
   defaultTab?: string;
   headerControls?: React.ReactNode;
 }

website/src/components/Playground/Preview.tsx

@@ -22,10 +22,8 @@ function Preview<T>({
   fixtures,
   getInitialInterceptorData,
 }: PreviewProps<T>) {
-  const [choice, setTabGroupChoice] = useTabStorage(
-    `docusaurus.tab.${groupId}`,
-  );
-  const selectedValue = (choice ?? defaultOpen) as 'y' | 'n';
+  const [choice, setTabGroupChoice] = useTabStorage(groupId);
+  const selectedValue = choice === 'y' || choice === 'n' ? choice : defaultOpen;
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
 

website/src/components/Playground/editor/EditorSurface.tsx

@@ -11,7 +11,6 @@ import React, {
 import { LiveEditor } from 'react-live';
 
 import Header from '../Header';
-import { isGoogleBot } from '../isMobileOrBot';
 import Editor from '../PlaygroundEditor';
 import styles from '../styles.module.css';
 import TabList from '../TabList';
@@ -20,6 +19,8 @@ import type { CodeDocument, CodeModel } from './codeModel';
 export interface EditorSurfaceProps extends CodeModel {
   layout: 'row' | 'stacked';
   variant: 'playground' | 'standalone';
+  /** When false, keep static SSR-friendly editors (no Monaco). Defaults true. */
+  interactive?: boolean;
   fixtureContent?: React.ReactNode;
   headerControls?: React.ReactNode;
 }
@@ -29,6 +30,7 @@ export default function EditorSurface({
   update,
   layout,
   variant,
+  interactive = true,
   fixtureContent,
   headerControls,
 }: EditorSurfaceProps) {
@@ -103,6 +105,7 @@ export default function EditorSurface({
           : null}
           <TextEditTab
             hidden={closedList[index]}
+            interactive={interactive}
             tabIndex={index}
             onFocus={
               row && !document.col && documents.length > 1 ?
@@ -125,18 +128,33 @@ export default function EditorSurface({
 
 function TextEditTab({
   hidden,
+  interactive,
   code,
   language,
   tabIndex,
   ...rest
-}: ComponentProps<typeof Editor> & { hidden: boolean }) {
-  const fallback =
-    hidden ? <></>
-    : isGoogleBot ?
-      <pre className="prism-code language-tsx" spellCheck="false">
-        {code}
-      </pre>
-    : <LiveEditor language={language} code={code} disabled />;
+}: ComponentProps<typeof Editor> & {
+  hidden: boolean;
+  interactive: boolean;
+}) {
+  // Stable across SSR/hydration (do not branch on navigator / isGoogleBot here).
+  const staticView = <LiveEditor language={language} code={code} disabled />;
+
+  // Deferred protocols: keep open-file source in the DOM for SSG/crawlers;
+  // skip Monaco until the sandbox has been shown once.
+  if (!interactive) {
+    return (
+      <div
+        className={clsx(styles.playgroundEditor, {
+          [styles.hidden]: hidden,
+        })}
+      >
+        {hidden ? null : staticView}
+      </div>
+    );
+  }
+
+  const fallback = hidden ? <></> : staticView;
 
   return (
     <div

website/src/components/Playground/index.tsx

@@ -1,6 +1,7 @@
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useIsomorphicLayoutEffect from '@docusaurus/useIsomorphicLayoutEffect';
 import clsx from 'clsx';
-import React, { lazy, useDeferredValue } from 'react';
+import React, { lazy, useDeferredValue, useState } from 'react';
 
 import Boundary from './Boundary';
 import { useCodeDocuments } from './editor/codeModel';
@@ -55,6 +56,7 @@ export default function Playground<T>({
         <PlaygroundContent
           reverse={playgroundPosition === 'top'}
           row={row}
+          hidden={hidden}
           fixtures={fixtures}
           groupId={groupId}
           defaultOpen={defaultOpen}
@@ -73,6 +75,7 @@ function PlaygroundContent<T>({
   reverse,
   children,
   row,
+  hidden,
   fixtures,
   groupId,
   defaultOpen,
@@ -85,10 +88,18 @@ function PlaygroundContent<T>({
   const code = useDeferredValue(
     model.documents.map(document => document.value).join('\n'),
   );
+
+  // Hydrate Monaco on first show and keep it (preserves undo / go-to-def).
+  const [editorInteractive, setEditorInteractive] = useState(!hidden);
+  useIsomorphicLayoutEffect(() => {
+    if (!hidden) setEditorInteractive(true);
+  }, [hidden]);
+
   const editor = (
     <EditorShell key="editor">
       <EditorSurface
         {...model}
+        interactive={editorInteractive}
         layout={row ? 'row' : 'stacked'}
         variant="playground"
         fixtureContent={
@@ -98,25 +109,28 @@ function PlaygroundContent<T>({
       />
     </EditorShell>
   );
-  const preview = (
-    <Boundary key="preview" fallback={previewLoading}>
-      <PreviewWithScopeLazy
-        code={code}
-        groupId={groupId}
-        defaultOpen={defaultOpen}
-        row={row}
-        fixtures={fixtures}
-        getInitialInterceptorData={getInitialInterceptorData}
-      />
-    </Boundary>
-  );
+  // Live preview only while visible — unmounts when hidden (resets store).
+  const preview =
+    hidden ? previewLoading : (
+      <Boundary key="preview" fallback={previewLoading}>
+        <PreviewWithScopeLazy
+          code={code}
+          groupId={groupId}
+          defaultOpen={defaultOpen}
+          row={row}
+          fixtures={fixtures}
+          getInitialInterceptorData={getInitialInterceptorData}
+        />
+      </Boundary>
+    );
 
   return <>{reverse ? [preview, editor] : [editor, preview]}</>;
 }
 
 interface ContentProps<T> extends PreviewProps<T> {
   children: PlaygroundProps<T>['children'];
   reverse: boolean;
+  hidden: boolean;
   defaultTab?: string;
   headerControls?: React.ReactNode;
 }

website/src/utils/tabStorage.ts

@@ -1,14 +1,15 @@
 import { useStorageSlot } from '@docusaurus/theme-common';
 import { useCallback } from 'react';
 
-export function useTabStorage(groupId: string) {
-  const key = getStorageKey(groupId);
+/** Persist a tab choice under `docusaurus.tab.${groupId}`. Pass the raw group id. */
+export function useTabStorage(groupId: string | null | undefined) {
+  const key = groupId ? `docusaurus.tab.${groupId}` : null;
   const [value, storageSlot] = useStorageSlot(key);
 
   const setValue = useCallback(
     (newValue: string) => {
       if (!key) {
-        return; // no-op
+        return;
       }
       storageSlot.set(newValue);
     },
@@ -17,5 +18,3 @@ export function useTabStorage(groupId: string) {
 
   return [value, setValue] as const;
 }
-
-const getStorageKey = (groupId: string) => `docusaurus.tab.${groupId}`;