fix: update api playground ctrl+` interaction and add the command to the command bar.

packages/ui/app/src/atoms/playground.ts

@@ -37,7 +37,7 @@ import { FEATURE_FLAGS_ATOM } from "./flags";
 import { useAtomEffect } from "./hooks";
 import { HEADER_HEIGHT_ATOM } from "./layout";
 import { LOCATION_ATOM } from "./location";
-import { NAVIGATION_NODES_ATOM } from "./navigation";
+import { CURRENT_NODE_ATOM, NAVIGATION_NODES_ATOM } from "./navigation";
 import { atomWithStorageValidation } from "./utils/atomWithStorageValidation";
 import { IS_MOBILE_SCREEN_ATOM } from "./viewport";
 
@@ -136,14 +136,14 @@ export function useClosePlayground(): () => void {
     });
 }
 
-export function useOpenPlayground(): (nodeId?: FernNavigation.NodeId) => void {
-    const setNodeId = useSetAtom(PLAYGROUND_NODE_ID);
-    const prevNodeId = useAtomValue(PREV_PLAYGROUND_NODE_ID);
-    return useEventCallback((nodeId?: FernNavigation.NodeId) => {
-        // TODO: "" implicitly means open + empty state. This is a hack and we should rethink the UX.
-        setNodeId(nodeId ?? prevNodeId ?? FernNavigation.NodeId(""));
-    });
-}
+// export function useOpenPlayground(): (nodeId?: FernNavigation.NodeId) => void {
+//     const setNodeId = useSetAtom(PLAYGROUND_NODE_ID);
+//     const prevNodeId = useAtomValue(PREV_PLAYGROUND_NODE_ID);
+//     return useEventCallback((nodeId?: FernNavigation.NodeId) => {
+//         // TODO: "" implicitly means open + empty state. This is a hack and we should rethink the UX.
+//         setNodeId(nodeId ?? prevNodeId ?? FernNavigation.NodeId(""));
+//     });
+// }
 
 export function useTogglePlayground(): () => void {
     const isPlaygroundOpen = useIsPlaygroundOpen();
@@ -153,7 +153,7 @@ export function useTogglePlayground(): () => void {
         if (isPlaygroundOpen) {
             closePlayground();
         } else {
-            openPlayground();
+            void openPlayground();
         }
     });
 }
@@ -345,12 +345,42 @@ export const usePlaygroundFormStateAtom = (
     return formStateAtom;
 };
 
-export function useSetAndOpenPlayground(): (node: FernNavigation.NavigationNodeApiLeaf) => Promise<void> {
+const API_LEAF_NODES = atom((get) => get(NAVIGATION_NODES_ATOM).getNodesInOrder().filter(FernNavigation.isApiLeaf));
+export const HAS_API_PLAYGROUND = atom((get) => get(IS_PLAYGROUND_ENABLED_ATOM) && get(API_LEAF_NODES).length > 0);
+
+export function useOpenPlayground(): (node?: FernNavigation.NavigationNodeApiLeaf) => Promise<void> {
     const preload = usePreloadApiLeaf();
 
     return useAtomCallback(
         useCallbackOne(
-            async (get, set, node: FernNavigation.NavigationNodeApiLeaf) => {
+            async (get, set, node?: FernNavigation.NavigationNodeApiLeaf) => {
+                if (!get(HAS_API_PLAYGROUND)) {
+                    set(PLAYGROUND_NODE_ID, undefined);
+                    return;
+                }
+
+                if (node == null) {
+                    const prevNodeId = get(PREV_PLAYGROUND_NODE_ID);
+                    if (prevNodeId != null && get(API_LEAF_NODES).some((n) => n.id === prevNodeId)) {
+                        set(PLAYGROUND_NODE_ID, prevNodeId);
+                        return;
+                    }
+
+                    // if no previous node, use the current node (if it's an API leaf)
+                    const currentNode = get(CURRENT_NODE_ATOM);
+                    if (currentNode != null && FernNavigation.isApiLeaf(currentNode)) {
+                        set(PLAYGROUND_NODE_ID, currentNode.id);
+                        return;
+                    }
+
+                    // get the first API leaf node
+                    const firstApiLeafNode = get(API_LEAF_NODES)[0];
+                    if (firstApiLeafNode != null) {
+                        set(PLAYGROUND_NODE_ID, firstApiLeafNode.id);
+                    }
+                    return;
+                }
+
                 const formStateAtom = playgroundFormStateFamily(node.id);
                 set(PLAYGROUND_NODE_ID, node.id);
 

packages/ui/app/src/playground/PlaygroundButton.tsx

@@ -3,13 +3,13 @@ import { FernButton, FernTooltip, FernTooltipProvider } from "@fern-ui/component
 import { PlaySolid } from "iconoir-react";
 import { useAtomValue } from "jotai";
 import { FC } from "react";
-import { IS_PLAYGROUND_ENABLED_ATOM, useSetAndOpenPlayground } from "../atoms";
+import { IS_PLAYGROUND_ENABLED_ATOM, useOpenPlayground } from "../atoms";
 import { usePlaygroundSettings } from "../hooks/usePlaygroundSettings";
 
 export const PlaygroundButton: FC<{
     state: FernNavigation.NavigationNodeApiLeaf;
 }> = ({ state }) => {
-    const openPlayground = useSetAndOpenPlayground();
+    const openPlayground = useOpenPlayground();
     const isPlaygroundEnabled = useAtomValue(IS_PLAYGROUND_ENABLED_ATOM);
     const settings = usePlaygroundSettings(state.id);
 

packages/ui/app/src/playground/endpoint/PlaygroundEndpointSelectorLeafNode.tsx

@@ -4,7 +4,7 @@ import { atom, useAtomValue } from "jotai";
 import dynamic from "next/dynamic";
 import { ReactElement, forwardRef } from "react";
 import { useMemoOne } from "use-memo-one";
-import { getApiDefinitionAtom, useSetAndOpenPlayground } from "../../atoms";
+import { getApiDefinitionAtom, useOpenPlayground } from "../../atoms";
 import { HttpMethodTag } from "../../components/HttpMethodTag";
 import { usePreloadApiLeaf } from "../hooks/usePreloadApiLeaf";
 
@@ -41,7 +41,7 @@ export const PlaygroundEndpointSelectorLeafNode = forwardRef<HTMLLIElement, Play
             ),
         );
 
-        const setSelectionStateAndOpen = useSetAndOpenPlayground();
+        const setSelectionStateAndOpen = useOpenPlayground();
 
         const createSelectEndpoint = (endpoint: FernNavigation.NavigationNodeApiLeaf) => () => {
             void setSelectionStateAndOpen(endpoint);

packages/ui/app/src/search/SearchV2.tsx

@@ -2,6 +2,7 @@
     CommandActions,
     CommandEmpty,
     CommandGroupFilters,
+    CommandGroupPlayground,
     CommandGroupTheme,
     CommandSearchHits,
     DesktopBackButton,
@@ -26,10 +27,13 @@
 import {
     CURRENT_VERSION_ATOM,
     DOMAIN_ATOM,
+    HAS_API_PLAYGROUND,
     THEME_SWITCH_ENABLED_ATOM,
     atomWithStorageString,
     useFernUser,
+    useIsPlaygroundOpen,
     useSetTheme,
+    useTogglePlayground,
 } from "../atoms";
 import { useApiRoute } from "../hooks/useApiRoute";
 import { useApiRouteSWRImmutable } from "../hooks/useApiRouteSWR";
@@ -56,8 +60,8 @@
 
     const [open, setOpen] = useCommandTrigger();
     const domain = useAtomValue(DOMAIN_ATOM);
     const isThemeSwitchEnabled = useAtomValue(THEME_SWITCH_ENABLED_ATOM);
     const setTheme = useSetTheme();
 
     const { data } = useApiRouteSWRImmutable("/api/fern-docs/search/v2/key", {
         request: { headers: { "X-User-Token": userToken } },
@@ -112,13 +116,51 @@
                     <CommandGroupFilters />
                     <CommandEmpty />
                     <RouterAwareCommandSearchHits onClose={() => setOpen(false)} />
-                    <CommandActions>{isThemeSwitchEnabled && <CommandGroupTheme setTheme={setTheme} />}</CommandActions>
+                    <CommandActions>
+                        <CommandPlayground onClose={() => setOpen(false)} />
+                        <CommandTheme onClose={() => setOpen(false)} />
+                    </CommandActions>
                 </DesktopCommand>
             </DesktopSearchDialog>
         </SearchClientRoot>
     );
 }
 
+function CommandPlayground({ onClose }: { onClose: () => void }) {
+    const hasApiPlayground = useAtomValue(HAS_API_PLAYGROUND);
+    const togglePlayground = useTogglePlayground();
+    const playgroundOpen = useIsPlaygroundOpen();
+
+    if (!hasApiPlayground) {
+        return null;
+    }
+    return (
+        <CommandGroupPlayground
+            togglePlayground={() => {
+                togglePlayground();
+                onClose();
+            }}
+            playgroundOpen={playgroundOpen}
+        />
+    );
+}
+
+function CommandTheme({ onClose }: { onClose: () => void }) {
+    const isThemeSwitchEnabled = useAtomValue(THEME_SWITCH_ENABLED_ATOM);
+    const setTheme = useSetTheme();
+    if (!isThemeSwitchEnabled) {
+        return null;
+    }
+    return (
+        <CommandGroupTheme
+            setTheme={(theme) => {
+                setTheme(theme);
+                onClose();
+            }}
+        />
+    );
+}
+
 function RouterAwareCommandSearchHits({ onClose }: { onClose: () => void }) {
     const router = useRouter();
 

packages/ui/fern-docs-search-ui/src/components/shared/command-playground.tsx

@@ -0,0 +1,31 @@
+import { Kbd } from "@fern-ui/components";
+import { Command } from "cmdk";
+import { Play } from "lucide-react";
+import { ComponentPropsWithoutRef, forwardRef } from "react";
+
+export const CommandGroupPlayground = forwardRef<
+    HTMLDivElement,
+    ComponentPropsWithoutRef<typeof Command.Group> & {
+        togglePlayground?: () => void;
+        playgroundOpen?: boolean;
+    }
+>(({ togglePlayground, playgroundOpen, ...props }, ref) => {
+    if (togglePlayground == null) {
+        return false;
+    }
+
+    return (
+        <Command.Group heading="API Playground" ref={ref} {...props}>
+            <Command.Item
+                value={playgroundOpen ? "close api playground" : "open api playground"}
+                onSelect={() => togglePlayground()}
+            >
+                <Play />
+                {playgroundOpen ? "Close API Playground" : "Open API Playground"}
+                <Kbd className="ml-auto">ctrl+&#96;</Kbd>
+            </Command.Item>
+        </Command.Group>
+    );
+});
+
+CommandGroupPlayground.displayName = "CommandGroupPlayground";

packages/ui/fern-docs-search-ui/src/components/shared/index.ts

@@ -2,5 +2,6 @@ export * from "./command-actions";
 export * from "./command-empty";
 export * from "./command-filters";
 export * from "./command-hits";
+export * from "./command-playground";
 export * from "./command-theme";
 export * from "./command-ux";