@brainfish-ai/devdoc 0.1.43 → 0.1.45

package/renderer/components/docs-viewer/playground/graphql-playground.js

@@ -6,12 +6,182 @@ import { Play, ArrowClockwise, Copy, Check, Spinner, X, FileText, BracketsCurly,
 import { Button } from '@/components/ui/button';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
 import Editor, { loader } from '@monaco-editor/react';
-// Configure Monaco to use CDN
+import { buildSchema } from 'graphql';
+import { getAutocompleteSuggestions, CompletionItemKind } from 'graphql-language-service';
+// Configure Monaco to load from CDN
 loader.config({
     paths: {
         vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.45.0/min/vs'
     }
 });
+// Store parsed schema and completion provider disposable
+let parsedSchema = null;
+let completionProviderDisposable = null;
+// Map graphql-language-service completion kinds to Monaco kinds
+function toMonacoCompletionKind(kind, monaco) {
+    const mKinds = monaco.languages.CompletionItemKind;
+    switch(kind){
+        case CompletionItemKind.Field:
+            return mKinds.Field;
+        case CompletionItemKind.Variable:
+            return mKinds.Variable;
+        case CompletionItemKind.Property:
+            return mKinds.Property;
+        case CompletionItemKind.EnumMember:
+            return mKinds.EnumMember;
+        case CompletionItemKind.Class:
+            return mKinds.Class;
+        case CompletionItemKind.Interface:
+            return mKinds.Interface;
+        case CompletionItemKind.Function:
+            return mKinds.Function;
+        case CompletionItemKind.Snippet:
+            return mKinds.Snippet;
+        case CompletionItemKind.Keyword:
+            return mKinds.Keyword;
+        case CompletionItemKind.Constant:
+            return mKinds.Constant;
+        case CompletionItemKind.Enum:
+            return mKinds.Enum;
+        default:
+            return mKinds.Text;
+    }
+}
+// Find fields already selected in the current selection set
+function getExistingFieldsInSelectionSet(documentText, cursorOffset) {
+    const existingFields = new Set();
+    // Find the opening brace of the current selection set
+    let braceCount = 0;
+    let selectionSetStart = -1;
+    for(let i = cursorOffset - 1; i >= 0; i--){
+        const char = documentText[i];
+        if (char === '}') braceCount++;
+        if (char === '{') {
+            if (braceCount === 0) {
+                selectionSetStart = i;
+                break;
+            }
+            braceCount--;
+        }
+    }
+    if (selectionSetStart === -1) return existingFields;
+    // Find the closing brace
+    braceCount = 1;
+    let selectionSetEnd = documentText.length;
+    for(let i = selectionSetStart + 1; i < documentText.length; i++){
+        const char = documentText[i];
+        if (char === '{') braceCount++;
+        if (char === '}') {
+            braceCount--;
+            if (braceCount === 0) {
+                selectionSetEnd = i;
+                break;
+            }
+        }
+    }
+    // Extract the selection set content
+    const selectionSetContent = documentText.slice(selectionSetStart + 1, selectionSetEnd);
+    // Parse field names - match field names that appear on their own or with arguments/aliases
+    // Matches: fieldName, fieldName(args), alias: fieldName, ...fieldName
+    const lines = selectionSetContent.split('\n');
+    for (const line of lines){
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue; // Skip empty lines and comments
+        // Match field name at start of line (possibly with alias)
+        // Pattern: optionalAlias: fieldName or just fieldName
+        const fieldMatch = trimmed.match(/^(?:\.\.\.)?(?:[a-zA-Z_][a-zA-Z0-9_]*\s*:\s*)?([a-zA-Z_][a-zA-Z0-9_]*)/);
+        if (fieldMatch) {
+            const fieldName = fieldMatch[1];
+            // Skip GraphQL keywords but include __typename
+            if (![
+                'query',
+                'mutation',
+                'subscription',
+                'fragment',
+                'on'
+            ].includes(fieldName)) {
+                existingFields.add(fieldName);
+            }
+        }
+    }
+    return existingFields;
+}
+// Register GraphQL completion provider using graphql-language-service
+function registerGraphQLCompletionProvider(monaco, schema) {
+    // Dispose previous provider if exists
+    if (completionProviderDisposable) {
+        completionProviderDisposable.dispose();
+    }
+    completionProviderDisposable = monaco.languages.registerCompletionItemProvider('graphql', {
+        triggerCharacters: [
+            '{',
+            '(',
+            ' ',
+            ':',
+            '$',
+            '@',
+            '.',
+            '\n'
+        ],
+        provideCompletionItems: (model, position)=>{
+            const documentText = model.getValue();
+            const cursorOffset = model.getOffsetAt(position);
+            // graphql-language-service Position interface
+            const gqlPosition = {
+                line: position.lineNumber - 1,
+                character: position.column - 1,
+                setLine: (line)=>{
+                    gqlPosition.line = line;
+                },
+                setCharacter: (char)=>{
+                    gqlPosition.character = char;
+                },
+                lessThanOrEqualTo: (other)=>{
+                    return gqlPosition.line < other.line || gqlPosition.line === other.line && gqlPosition.character <= other.character;
+                }
+            };
+            try {
+                // Get completions from graphql-language-service
+                const completions = getAutocompleteSuggestions(schema, documentText, gqlPosition);
+                // Get existing fields in current selection set to filter them out
+                const existingFields = getExistingFieldsInSelectionSet(documentText, cursorOffset);
+                // Filter out already-selected fields (only for Field kind suggestions)
+                const filteredCompletions = completions.filter((item)=>{
+                    // Only filter out Field suggestions (kind = 5), keep keywords, types, etc.
+                    if (item.kind === CompletionItemKind.Field) {
+                        return !existingFields.has(item.label);
+                    }
+                    return true;
+                });
+                const word = model.getWordUntilPosition(position);
+                const range = {
+                    startLineNumber: position.lineNumber,
+                    endLineNumber: position.lineNumber,
+                    startColumn: word.startColumn,
+                    endColumn: word.endColumn
+                };
+                const suggestions = filteredCompletions.map((item, index)=>({
+                        label: item.label,
+                        kind: toMonacoCompletionKind(item.kind, monaco),
+                        insertText: item.insertText || item.label,
+                        insertTextRules: item.insertText?.includes('$') ? monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet : undefined,
+                        detail: item.detail || undefined,
+                        documentation: item.documentation || undefined,
+                        sortText: String(index).padStart(5, '0'),
+                        range
+                    }));
+                return {
+                    suggestions
+                };
+            } catch (err) {
+                console.error('[GraphQL Playground] Completion error:', err);
+                return {
+                    suggestions: []
+                };
+            }
+        }
+    });
+}
 const STORAGE_KEY = 'brainfish-graphql-playground';
 // ============================================================================
 // Helpers
@@ -184,7 +354,7 @@ export function GraphQLPlayground({ endpoint, defaultQuery = `# Welcome to the G
 query {
   __typename
 }
-`, headers: defaultHeaders = {}, operations = [], selectedOperationId: externalSelectedId, hideExplorer = false, className, theme = 'dark' }) {
+`, headers: defaultHeaders = {}, operations = [], selectedOperationId: externalSelectedId, hideExplorer = false, className, theme = 'dark', schemaSDL }) {
     const [query, setQuery] = useState(defaultQuery);
     const [variables, setVariables] = useState('{}');
     const [customHeaders, setCustomHeaders] = useState(Object.keys(defaultHeaders).length > 0 ? JSON.stringify(defaultHeaders, null, 2) : '{}');
@@ -199,6 +369,35 @@ query {
     const selectedOperationId = externalSelectedId ?? internalSelectedId;
     const abortControllerRef = useRef(null);
     const hasLoadedRef = useRef(false);
+    const monacoRef = useRef(null);
+    // Initialize Monaco GraphQL when editor mounts
+    const handleEditorDidMount = useCallback((editor, monaco)=>{
+        monacoRef.current = monaco;
+        // Parse schema and register completion provider
+        if (schemaSDL) {
+            try {
+                parsedSchema = buildSchema(schemaSDL);
+                registerGraphQLCompletionProvider(monaco, parsedSchema);
+            } catch (err) {
+                console.error('[GraphQL Playground] Failed to parse schema:', err);
+            }
+        }
+    }, [
+        schemaSDL
+    ]);
+    // Update completion provider when schema changes
+    useEffect(()=>{
+        if (schemaSDL && monacoRef.current) {
+            try {
+                parsedSchema = buildSchema(schemaSDL);
+                registerGraphQLCompletionProvider(monacoRef.current, parsedSchema);
+            } catch (err) {
+                console.error('[GraphQL Playground] Failed to update schema:', err);
+            }
+        }
+    }, [
+        schemaSDL
+    ]);
     // Load from localStorage on mount
     useEffect(()=>{
         const stored = loadStoredState();
@@ -478,6 +677,7 @@ query {
                                                         height: "100%",
                                                         language: "graphql",
                                                         value: query,
+                                                        onMount: handleEditorDidMount,
                                                         onChange: (value)=>{
                                                             setQuery(value || '');
                                                             setInternalSelectedId(undefined); // Clear internal selection when manually editing
@@ -502,7 +702,9 @@ query {
                                                             },
                                                             wordWrap: 'on',
                                                             automaticLayout: true,
-                                                            tabSize: 2
+                                                            tabSize: 2,
+                                                            quickSuggestions: true,
+                                                            suggestOnTriggerCharacters: true
                                                         },
                                                         loading: /*#__PURE__*/ _jsxs("div", {
                                                             className: "flex items-center justify-center h-full text-muted-foreground text-sm",

package/renderer/components/docs-viewer/sidebar/right-sidebar.js

@@ -2,15 +2,14 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useState, useCallback } from 'react';
 import { createPortal } from 'react-dom';
-import Image from 'next/image';
-import { X, ArrowClockwise } from '@phosphor-icons/react';
+import { X, ArrowClockwise, Sparkle } from '@phosphor-icons/react';
 import { AgentChat } from '../agent';
 import { Button } from '@/components/ui/button';
 import { useMobile } from '@/lib/api-docs/mobile-context';
 import { cn } from '@/lib/utils';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
 export function RightSidebar({ request, collection, apiSummary, onNavigateToEndpoint, onPrefillParameters, debugContext, onClearDebugContext, explainContext, onClearExplainContext, onOpenGlobalAuth, onNavigateToAuthTab, onNavigateToParamsTab, onNavigateToBodyTab, onNavigateToHeadersTab, onNavigateToDocSection, onNavigateToDocPage }) {
-    // Mobile context
+    // Mobile context - now used for both mobile and desktop
     const { isMobile, isRightSidebarOpen, closeRightSidebar } = useMobile();
     const [mounted, setMounted] = useState(false);
     // Ensure we're mounted before using portal (for SSR)
@@ -46,7 +45,7 @@ export function RightSidebar({ request, collection, apiSummary, onNavigateToEndp
         setChatKey((prev)=>prev + 1);
         setHasMessages(false);
     }, []);
-    // Sidebar content component (shared between mobile and desktop)
+    // Sidebar content component
     const sidebarContent = /*#__PURE__*/ _jsxs(_Fragment, {
         children: [
             /*#__PURE__*/ _jsx("div", {
@@ -57,15 +56,9 @@ export function RightSidebar({ request, collection, apiSummary, onNavigateToEndp
                         /*#__PURE__*/ _jsxs("div", {
                             className: "docs-agent-title flex items-center gap-2.5",
                             children: [
-                                /*#__PURE__*/ _jsx("div", {
-                                    className: "docs-agent-avatar size-7 rounded-full overflow-hidden bg-muted flex items-center justify-center shrink-0",
-                                    children: /*#__PURE__*/ _jsx(Image, {
-                                        src: "/icon.png",
-                                        alt: "Assistant",
-                                        width: 28,
-                                        height: 28,
-                                        className: "size-7 object-cover"
-                                    })
+                                /*#__PURE__*/ _jsx(Sparkle, {
+                                    className: "size-5 text-primary",
+                                    weight: "fill"
                                 }),
                                 /*#__PURE__*/ _jsx("span", {
                                     className: "text-sm font-medium",
@@ -97,15 +90,26 @@ export function RightSidebar({ request, collection, apiSummary, onNavigateToEndp
                                         })
                                     ]
                                 }),
-                                isMobile && /*#__PURE__*/ _jsx(Button, {
-                                    variant: "ghost",
-                                    size: "icon",
-                                    onClick: closeRightSidebar,
-                                    className: "h-7 w-7 lg:hidden",
-                                    children: /*#__PURE__*/ _jsx(X, {
-                                        className: "h-4 w-4",
-                                        weight: "bold"
-                                    })
+                                /*#__PURE__*/ _jsxs(Tooltip, {
+                                    children: [
+                                        /*#__PURE__*/ _jsx(TooltipTrigger, {
+                                            asChild: true,
+                                            children: /*#__PURE__*/ _jsx(Button, {
+                                                variant: "ghost",
+                                                size: "icon",
+                                                onClick: closeRightSidebar,
+                                                className: "h-7 w-7 text-muted-foreground hover:text-foreground",
+                                                children: /*#__PURE__*/ _jsx(X, {
+                                                    className: "h-4 w-4",
+                                                    weight: "bold"
+                                                })
+                                            })
+                                        }),
+                                        /*#__PURE__*/ _jsx(TooltipContent, {
+                                            side: "bottom",
+                                            children: "Close"
+                                        })
+                                    ]
                                 })
                             ]
                         })
@@ -136,28 +140,20 @@ export function RightSidebar({ request, collection, apiSummary, onNavigateToEndp
             })
         ]
     });
-    // Mobile sidebar rendered via portal to escape stacking context
-    const mobileSidebar = mounted && isMobile ? /*#__PURE__*/ createPortal(/*#__PURE__*/ _jsxs(_Fragment, {
+    // Render via portal for proper z-index stacking (both mobile and desktop)
+    if (!mounted) return null;
+    return /*#__PURE__*/ createPortal(/*#__PURE__*/ _jsxs(_Fragment, {
         children: [
-            isRightSidebarOpen && /*#__PURE__*/ _jsx("div", {
-                className: "docs-agent-overlay fixed inset-0 bg-black/50 z-[55] lg:hidden",
+            isMobile && isRightSidebarOpen && /*#__PURE__*/ _jsx("div", {
+                className: "docs-agent-overlay fixed inset-0 bg-black/50 z-[55]",
                 onClick: closeRightSidebar
             }),
             /*#__PURE__*/ _jsx("div", {
-                className: cn("docs-agent-panel border-l border-border bg-background flex flex-col overflow-hidden", "fixed inset-y-0 right-0 z-[60] w-[320px] sm:w-[360px] h-full", "transform transition-transform duration-300 ease-in-out", !isRightSidebarOpen && "translate-x-full", isRightSidebarOpen && "translate-x-0"),
+                className: cn("docs-agent-panel border-l border-border bg-background flex flex-col overflow-hidden", "fixed inset-y-0 right-0 z-[60]", // Width: smaller on mobile, full 384px on desktop
+                "w-[320px] sm:w-[360px] lg:w-96", // Slide animation
+                "transform transition-transform duration-300 ease-in-out", isRightSidebarOpen ? "translate-x-0" : "translate-x-full"),
                 children: sidebarContent
             })
         ]
-    }), document.body) : null;
-    // Desktop sidebar rendered in place
-    const desktopSidebar = !isMobile ? /*#__PURE__*/ _jsx("div", {
-        className: cn("docs-agent-panel border-l border-border bg-background flex flex-col overflow-hidden", "relative w-96 h-full"),
-        children: sidebarContent
-    }) : null;
-    return /*#__PURE__*/ _jsxs(_Fragment, {
-        children: [
-            mobileSidebar,
-            desktopSidebar
-        ]
-    });
+    }), document.body);
 }

package/renderer/components/theme-toggle.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import { Moon, Sun, Desktop, Check } from "@phosphor-icons/react";
+import { Moon, Sun, Check } from "@phosphor-icons/react";
 import { useTheme } from "next-themes";
 import { Button } from "@/components/ui/button";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
@@ -78,26 +78,6 @@ export function ThemeToggle() {
                                 className: "h-4 w-4"
                             })
                         ]
-                    }),
-                    /*#__PURE__*/ _jsxs(DropdownMenuItem, {
-                        onClick: ()=>setTheme("system"),
-                        className: cn("flex items-center justify-between gap-2", mounted && theme === "system" && "bg-accent"),
-                        children: [
-                            /*#__PURE__*/ _jsxs("div", {
-                                className: "flex items-center gap-2",
-                                children: [
-                                    /*#__PURE__*/ _jsx(Desktop, {
-                                        className: "h-4 w-4"
-                                    }),
-                                    /*#__PURE__*/ _jsx("span", {
-                                        children: "System"
-                                    })
-                                ]
-                            }),
-                            mounted && theme === "system" && /*#__PURE__*/ _jsx(Check, {
-                                className: "h-4 w-4"
-                            })
-                        ]
                     })
                 ]
             })

package/renderer/hooks/use-route-state.js

@@ -0,0 +1,159 @@
+'use client';
+import { useState, useEffect, useCallback, useMemo } from 'react';
+/**
+ * Parse URL hash into route state
+ * 
+ * URL Schema:
+ * - #tab                              → Tab only, show default content (docs view)
+ * - #tab/page/{slug}                  → Doc page (docs view)
+ * - #tab/endpoint/{id}                → API endpoint (docs view)
+ * - #tab/endpoint/{id}/playground     → API endpoint (playground view)
+ * - #tab/endpoint/{id}/notes          → API endpoint (notes view)
+ * - #tab/page/{slug}/notes            → Doc page (notes view)
+ */ function parseHash(hash) {
+    // Remove leading # if present
+    const cleanHash = hash.startsWith('#') ? hash.slice(1) : hash;
+    // Default state
+    const defaultState = {
+        tab: null,
+        contentType: null,
+        contentId: null,
+        view: 'docs',
+        hash: cleanHash
+    };
+    if (!cleanHash) {
+        return defaultState;
+    }
+    // Split hash into parts: tab/type/id[/view]
+    const parts = cleanHash.split('/');
+    const tab = parts[0] || null;
+    const type = parts[1] || null;
+    // Check if last part is a view mode
+    const lastPart = parts[parts.length - 1];
+    const isViewSuffix = lastPart === 'playground' || lastPart === 'notes';
+    const view = isViewSuffix ? lastPart : 'docs';
+    // Get ID (everything between type and view, or type and end)
+    const idParts = isViewSuffix ? parts.slice(2, -1) : parts.slice(2);
+    const id = idParts.join('/') || null;
+    // Parse content type
+    let contentType = null;
+    if (type === 'endpoint') {
+        contentType = 'endpoint';
+    } else if (type === 'page') {
+        contentType = 'page';
+    } else if (type === 'section') {
+        contentType = 'section';
+    }
+    return {
+        tab,
+        contentType,
+        contentId: id,
+        view,
+        hash: cleanHash
+    };
+}
+/**
+ * Get the current hash from window.location
+ */ function getCurrentHash() {
+    if (typeof window === 'undefined') return '';
+    return window.location.hash;
+}
+/**
+ * Hook that provides URL-based route state
+ * 
+ * This hook is the single source of truth for page/content selection.
+ * It automatically updates when the URL hash changes (via navigation or browser back/forward).
+ * 
+ * @example
+ * const { tab, contentType, contentId } = useRouteState()
+ * 
+ * // Render based on content type
+ * if (contentType === 'page') {
+ *   return <DocPage slug={contentId} />
+ * }
+ */ export function useRouteState() {
+    const [hash, setHash] = useState(()=>getCurrentHash());
+    // Parse hash into route state
+    const state = useMemo(()=>parseHash(hash), [
+        hash
+    ]);
+    // Listen for hash changes
+    useEffect(()=>{
+        const handleHashChange = ()=>{
+            setHash(getCurrentHash());
+        };
+        // Listen for both hashchange and popstate (browser back/forward)
+        window.addEventListener('hashchange', handleHashChange);
+        window.addEventListener('popstate', handleHashChange);
+        // Set initial hash (in case it was set before this effect ran)
+        handleHashChange();
+        return ()=>{
+            window.removeEventListener('hashchange', handleHashChange);
+            window.removeEventListener('popstate', handleHashChange);
+        };
+    }, []);
+    return state;
+}
+/**
+ * Hook that provides navigation functions for updating the URL
+ * 
+ * @param defaultTab - Default tab to use when navigating
+ * @returns Navigation functions
+ */ export function useRouteNavigation(defaultTab) {
+    const navigateToPage = useCallback((slug, tab, view)=>{
+        const targetTab = tab || defaultTab || '';
+        const viewSuffix = view && view !== 'docs' ? `/${view}` : '';
+        window.location.hash = targetTab ? `${targetTab}/page/${slug}${viewSuffix}` : `page/${slug}${viewSuffix}`;
+    }, [
+        defaultTab
+    ]);
+    const navigateToEndpoint = useCallback((id, tab, view)=>{
+        const targetTab = tab || defaultTab || '';
+        const viewSuffix = view && view !== 'docs' ? `/${view}` : '';
+        window.location.hash = targetTab ? `${targetTab}/endpoint/${id}${viewSuffix}` : `endpoint/${id}${viewSuffix}`;
+    }, [
+        defaultTab
+    ]);
+    const navigateToSection = useCallback((sectionId, tab)=>{
+        const targetTab = tab || defaultTab || '';
+        window.location.hash = targetTab ? `${targetTab}/section/${sectionId}` : `section/${sectionId}`;
+    }, [
+        defaultTab
+    ]);
+    const navigateToTab = useCallback((tab)=>{
+        window.location.hash = tab;
+    }, []);
+    const clearSelection = useCallback((tab)=>{
+        const targetTab = tab || defaultTab;
+        if (targetTab) {
+            window.location.hash = targetTab;
+        } else {
+            // Remove hash entirely
+            window.history.pushState(null, '', window.location.pathname + window.location.search);
+        }
+    }, [
+        defaultTab
+    ]);
+    return {
+        navigateToPage,
+        navigateToEndpoint,
+        navigateToSection,
+        navigateToTab,
+        clearSelection
+    };
+}
+/**
+ * Utility to build hash URLs (for href attributes)
+ */ export const buildHashUrl = {
+    page: (tab, slug, view)=>{
+        const viewSuffix = view && view !== 'docs' ? `/${view}` : '';
+        return `#${tab}/page/${slug}${viewSuffix}`;
+    },
+    endpoint: (tab, id, view)=>{
+        const viewSuffix = view && view !== 'docs' ? `/${view}` : '';
+        return `#${tab}/endpoint/${id}${viewSuffix}`;
+    },
+    section: (tab, sectionId)=>`#${tab}/section/${sectionId}`,
+    tab: (tab)=>`#${tab}`
+};
+export { parseHash };

package/renderer/lib/api-docs/agent/use-suggestions.js

@@ -0,0 +1,97 @@
+'use client';
+import { useState, useEffect, useMemo } from 'react';
+/**
+ * Shared hook for fetching contextual suggestions
+ * Used by both AgentChat and AgentPopupButton
+ * 
+ * Server-side caching with KV (1 week TTL) - no client-side cache needed
+ */ export function useSuggestions({ currentEndpoint, endpointIndex = [], limit }) {
+    const [suggestions, setSuggestions] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    // Stable key for request deduplication
+    const requestKey = useMemo(()=>currentEndpoint?.id || `general:${endpointIndex.length}`, [
+        currentEndpoint?.id,
+        endpointIndex.length
+    ]);
+    // Fallback suggestions
+    const fallbackSuggestions = useMemo(()=>{
+        if (currentEndpoint) {
+            return [
+                {
+                    title: 'What does this',
+                    label: 'endpoint do?',
+                    prompt: `What does ${currentEndpoint.name} do?`
+                },
+                {
+                    title: 'What parameters',
+                    label: 'are required?',
+                    prompt: 'What parameters are required?'
+                },
+                {
+                    title: 'Python example',
+                    label: 'Show code',
+                    prompt: 'Show me a Python example'
+                }
+            ];
+        }
+        return [
+            {
+                title: 'Find an endpoint',
+                label: 'to create resources',
+                prompt: 'Find endpoints for creating resources'
+            },
+            {
+                title: 'How do I',
+                label: 'authenticate?',
+                prompt: 'How do I authenticate?'
+            },
+            {
+                title: 'Overview',
+                label: 'What can I do?',
+                prompt: 'What can I do with this API?'
+            }
+        ];
+    }, [
+        currentEndpoint
+    ]);
+    // Fetch suggestions from API (server handles KV caching)
+    useEffect(()=>{
+        let cancelled = false;
+        setIsLoading(true);
+        fetch('/api/suggestions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                endpointIndex,
+                currentEndpointId: currentEndpoint?.id
+            })
+        }).then((res)=>res.json()).then((data)=>{
+            if (cancelled) return;
+            if (data.suggestions) {
+                const allSuggestions = data.suggestions;
+                setSuggestions(limit ? allSuggestions.slice(0, limit) : allSuggestions);
+            }
+        }).catch((err)=>{
+            if (cancelled) return;
+            console.warn('[useSuggestions] Failed to fetch suggestions:', err);
+            setSuggestions(limit ? fallbackSuggestions.slice(0, limit) : fallbackSuggestions);
+        }).finally(()=>{
+            if (!cancelled) setIsLoading(false);
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        requestKey,
+        currentEndpoint,
+        endpointIndex,
+        limit,
+        fallbackSuggestions
+    ]);
+    return {
+        suggestions,
+        isLoading
+    };
+}