@brainfish-ai/devdoc 0.1.43 → 0.1.45

package/renderer/components/docs-viewer/index.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState, useCallback, useRef } from 'react';
+import { useEffect, useState, useCallback, useRef, useMemo } from 'react';
 import { Spinner } from '@phosphor-icons/react';
 import { DocsSidebar } from './sidebar';
 import { NotFoundPage } from './content/not-found-page';
@@ -11,7 +11,7 @@ import { DocPage } from './content/doc-page';
 import { ChangelogPage } from './content/changelog-page';
 import { GraphQLPlayground } from './playground/graphql-playground';
 import { makeBrainfishCollection } from '@/lib/api-docs/factories';
-import { parse, Kind } from 'graphql';
+import { buildSchema, isNonNullType, isListType } from 'graphql';
 import { GlobalAuthModal } from './global-auth-modal';
 import { AuthProvider } from '@/lib/api-docs/auth';
 import { PlaygroundProvider, usePlaygroundPrefill } from '@/lib/api-docs/playground/context';
@@ -27,57 +27,59 @@ import { Code, TestTube, Book } from '@phosphor-icons/react';
 import { cn } from '@/lib/utils';
 import { SearchDialog, useSearch } from './search';
 import { useTheme } from 'next-themes';
-// Helper to convert GraphQL TypeNode to string
-function typeNodeToString(typeNode) {
-    switch(typeNode.kind){
-        case Kind.NAMED_TYPE:
-            return typeNode.name.value;
-        case Kind.NON_NULL_TYPE:
-            return `${typeNodeToString(typeNode.type)}!`;
-        case Kind.LIST_TYPE:
-            return `[${typeNodeToString(typeNode.type)}]`;
-        default:
-            return 'Unknown';
+import { useRouteState } from '@/hooks/use-route-state';
+import { navigateToPage, navigateToEndpoint, navigateToSection, navigateToTab } from '@/lib/docs-navigation';
+import { useMobile } from '@/lib/api-docs/mobile-context';
+import { AgentPopupButton } from './agent/agent-popup-button';
+import { buildEndpointIndex } from '@/lib/api-docs/agent/indexer';
+// Helper to convert GraphQL type to string representation
+function graphqlTypeToString(type) {
+    if (isNonNullType(type)) {
+        return `${graphqlTypeToString(type.ofType)}!`;
     }
+    if (isListType(type)) {
+        return `[${graphqlTypeToString(type.ofType)}]`;
+    }
+    // Named type
+    return type.name || 'Unknown';
 }
-// Parse GraphQL schema using the graphql library
+// Parse GraphQL schema using buildSchema (for SDL)
 function parseGraphQLSchema(schemaSDL) {
     const operations = [];
     try {
-        const ast = parse(schemaSDL);
-        // Find Query, Mutation, Subscription type definitions
-        for (const def of ast.definitions){
-            if (def.kind === Kind.OBJECT_TYPE_DEFINITION) {
-                const typeName = def.name.value;
-                // Only process root operation types
-                if (![
-                    'Query',
-                    'Mutation',
-                    'Subscription'
-                ].includes(typeName)) continue;
-                const operationType = typeName.toLowerCase();
-                // Process each field
-                for (const field of def.fields || []){
-                    const name = field.name.value;
-                    // Skip internal fields
-                    if (name.startsWith('_')) continue;
-                    // Get description
-                    const description = field.description?.value || null;
-                    // Get return type
-                    const returnType = typeNodeToString(field.type);
-                    // Build args string for query generation
-                    const args = (field.arguments || []).map((arg)=>`${arg.name.value}: ${typeNodeToString(arg.type)}`).join(', ');
-                    const query = generateGraphQLQuery(operationType, name, field.arguments || [], returnType);
-                    const exampleVariables = generateGraphQLVariables(field.arguments || []);
-                    operations.push({
-                        id: `${operationType}-${name}`,
-                        name,
-                        description,
-                        operationType,
-                        query,
-                        exampleVariables
-                    });
-                }
+        const schema = buildSchema(schemaSDL);
+        // Get root operation types
+        const rootTypes = [
+            {
+                type: schema.getQueryType(),
+                operationType: 'query'
+            },
+            {
+                type: schema.getMutationType(),
+                operationType: 'mutation'
+            },
+            {
+                type: schema.getSubscriptionType(),
+                operationType: 'subscription'
+            }
+        ];
+        for (const { type: rootType, operationType } of rootTypes){
+            if (!rootType) continue;
+            const fields = rootType.getFields();
+            for (const [fieldName, field] of Object.entries(fields)){
+                // Skip internal fields
+                if (fieldName.startsWith('_')) continue;
+                const returnType = graphqlTypeToString(field.type);
+                const query = generateGraphQLQueryFromField(operationType, fieldName, field.args, returnType, schema);
+                const exampleVariables = generateGraphQLVariablesFromArgs(field.args, schema);
+                operations.push({
+                    id: `${operationType}-${fieldName}`,
+                    name: fieldName,
+                    description: field.description || null,
+                    operationType,
+                    query,
+                    exampleVariables
+                });
             }
         }
     } catch (err) {
@@ -85,16 +87,59 @@ function parseGraphQLSchema(schemaSDL) {
     }
     return operations;
 }
-// Generate example GraphQL query from AST
-function generateGraphQLQuery(operationType, name, args, returnType) {
+// Get default fields for a type from schema
+function getDefaultFieldsForType(typeName, schema) {
+    const type = schema.getType(typeName);
+    if (!type || !('getFields' in type)) return [];
+    const fields = type.getFields();
+    const fieldNames = Object.keys(fields);
+    // Priority order for default fields
+    const priorityFields = [
+        'code',
+        'id',
+        'name',
+        'title',
+        'slug'
+    ];
+    const selectedFields = [];
+    // First, add priority fields if they exist
+    for (const pf of priorityFields){
+        if (fieldNames.includes(pf)) {
+            selectedFields.push(pf);
+            if (selectedFields.length >= 3) break;
+        }
+    }
+    // If we don't have enough, add other scalar fields
+    if (selectedFields.length < 3) {
+        for (const [fname, fdef] of Object.entries(fields)){
+            if (selectedFields.includes(fname)) continue;
+            const ftype = graphqlTypeToString(fdef.type).replace(/[\[\]!]/g, '').trim();
+            if ([
+                'String',
+                'Int',
+                'Float',
+                'Boolean',
+                'ID'
+            ].includes(ftype)) {
+                selectedFields.push(fname);
+                if (selectedFields.length >= 3) break;
+            }
+        }
+    }
+    return selectedFields.length > 0 ? selectedFields : [
+        '__typename'
+    ];
+}
+// Generate example GraphQL query from schema field
+function generateGraphQLQueryFromField(operationType, name, args, returnType, schema) {
     let query = `${operationType} ${name.charAt(0).toUpperCase() + name.slice(1)}`;
     if (args.length > 0) {
-        const varDefs = args.map((arg)=>`$${arg.name.value}: ${typeNodeToString(arg.type)}`).join(', ');
+        const varDefs = args.map((arg)=>`$${arg.name}: ${graphqlTypeToString(arg.type)}`).join(', ');
         query += `(${varDefs})`;
     }
     query += ` {\n  ${name}`;
     if (args.length > 0) {
-        const argPairs = args.map((arg)=>`${arg.name.value}: $${arg.name.value}`).join(', ');
+        const argPairs = args.map((arg)=>`${arg.name}: $${arg.name}`).join(', ');
         query += `(${argPairs})`;
     }
     const baseType = returnType.replace(/[\[\]!]/g, '').trim();
@@ -107,34 +152,126 @@ function generateGraphQLQuery(operationType, name, args, returnType) {
     ].includes(baseType)) {
         query += '\n}';
     } else {
-        query += ` {\n    id\n    __typename\n  }\n}`;
+        // Get actual fields from the schema for this type
+        const defaultFields = getDefaultFieldsForType(baseType, schema);
+        const fieldsStr = defaultFields.map((f)=>`    ${f}`).join('\n');
+        query += ` {\n${fieldsStr}\n  }\n}`;
     }
     return query;
 }
-// Generate example variables from AST args
-function generateGraphQLVariables(args) {
+// Generate example value for a GraphQL type
+function generateExampleValue(type, schema, depth = 0) {
+    // Prevent infinite recursion
+    if (depth > 3) return null;
+    // Unwrap NonNull
+    if (isNonNullType(type)) {
+        return generateExampleValue(type.ofType, schema, depth);
+    }
+    // Handle List types - return array with one example element
+    if (isListType(type)) {
+        const itemValue = generateExampleValue(type.ofType, schema, depth);
+        return itemValue !== null ? [
+            itemValue
+        ] : [];
+    }
+    // Get the named type
+    const typeName = type.name;
+    if (!typeName) return null;
+    // Built-in scalar types
+    switch(typeName){
+        case 'String':
+            return 'example';
+        case 'Int':
+            return 10;
+        case 'Float':
+            return 1.5;
+        case 'Boolean':
+            return true;
+        case 'ID':
+            return 'example-id';
+        // Common custom scalars
+        case 'DateTime':
+            return new Date().toISOString();
+        case 'Date':
+            return new Date().toISOString().split('T')[0];
+        case 'Time':
+            return '12:00:00';
+        case 'JSON':
+            return {};
+        case 'JSONObject':
+            return {};
+        case 'URL':
+            return 'https://example.com';
+        case 'URI':
+            return 'https://example.com';
+        case 'Email':
+            return 'user@example.com';
+        case 'EmailAddress':
+            return 'user@example.com';
+        case 'UUID':
+            return '550e8400-e29b-41d4-a716-446655440000';
+        case 'BigInt':
+            return '9007199254740991';
+        case 'Long':
+            return 9007199254740991;
+    }
+    // Check if it's an enum type
+    const schemaType = schema.getType(typeName);
+    if (schemaType && 'getValues' in schemaType) {
+        const enumType = schemaType;
+        const values = enumType.getValues();
+        if (values.length > 0) {
+            return values[0].name // Return first enum value
+            ;
+        }
+    }
+    // Check if it's an input object type
+    if (schemaType && 'getFields' in schemaType) {
+        const inputType = schemaType;
+        const fields = inputType.getFields();
+        const result = {};
+        // Only include required fields to keep examples concise
+        for (const [fieldName, field] of Object.entries(fields)){
+            if (isNonNullType(field.type)) {
+                // Use default value if available, otherwise generate
+                if (field.defaultValue !== undefined) {
+                    result[fieldName] = field.defaultValue;
+                } else {
+                    result[fieldName] = generateExampleValue(field.type, schema, depth + 1);
+                }
+            }
+        }
+        // If no required fields, include first optional field
+        if (Object.keys(result).length === 0) {
+            const firstField = Object.entries(fields)[0];
+            if (firstField) {
+                const [fname, fdef] = firstField;
+                // Use default value if available
+                if (fdef.defaultValue !== undefined) {
+                    result[fname] = fdef.defaultValue;
+                } else {
+                    result[fname] = generateExampleValue(fdef.type, schema, depth + 1);
+                }
+            }
+        }
+        return result;
+    }
+    // Unknown type - return null
+    return null;
+}
+// Generate example variables from GraphQL arguments
+function generateGraphQLVariablesFromArgs(args, schema) {
     const variables = {};
     for (const arg of args){
-        const name = arg.name.value;
-        const type = typeNodeToString(arg.type).replace(/[\[\]!]/g, '').trim();
-        switch(type){
-            case 'String':
-                variables[name] = 'example';
-                break;
-            case 'Int':
-                variables[name] = 1;
-                break;
-            case 'Float':
-                variables[name] = 1.0;
-                break;
-            case 'Boolean':
-                variables[name] = true;
-                break;
-            case 'ID':
-                variables[name] = '1';
-                break;
-            default:
-                variables[name] = {};
+        // First, check if the argument has a default value in the schema
+        if (arg.defaultValue !== undefined) {
+            variables[arg.name] = arg.defaultValue;
+        } else {
+            // Generate example value for arguments without defaults
+            const value = generateExampleValue(arg.type, schema, 0);
+            if (value !== null) {
+                variables[arg.name] = value;
+            }
         }
     }
     return variables;
@@ -271,18 +408,45 @@ function getFirstDocPageForTab(docGroups, tabId) {
 }
 function DocsContent() {
     const [collection, setCollection] = useState(null);
-    const [selectedRequest, setSelectedRequest] = useState(null);
-    const [selectedDocSection, setSelectedDocSection] = useState(null);
-    const [selectedDocPage, setSelectedDocPage] = useState(null);
-    const [activeTab, setActiveTab] = useState('api-reference');
     const [selectedApiVersion, setSelectedApiVersion] = useState(null);
     const [loading, setLoading] = useState(true);
     const [isVersionLoading, setIsVersionLoading] = useState(false) // For version switch only
     ;
     const [error, setError] = useState(null);
     const [showAuthModal, setShowAuthModal] = useState(false);
-    const [notFoundSlug, setNotFoundSlug] = useState(null) // Track 404 for invalid URLs
-    ;
+    // URL-based route state - single source of truth for selection
+    const routeState = useRouteState();
+    // Derive active tab from URL (with default fallback)
+    const activeTab = routeState.tab || 'api-reference';
+    // Derive selected doc page from URL
+    const selectedDocPage = routeState.contentType === 'page' ? routeState.contentId : null;
+    // Derive selected doc section from URL
+    const selectedDocSection = routeState.contentType === 'section' ? routeState.contentId : null;
+    // Derive selected request from URL by looking up in collection
+    const selectedRequest = useMemo(()=>{
+        if (routeState.contentType !== 'endpoint' || !routeState.contentId || !collection) {
+            return null;
+        }
+        return findRequestById(collection, routeState.contentId);
+    }, [
+        routeState.contentType,
+        routeState.contentId,
+        collection
+    ]);
+    // Derive not found slug from URL when endpoint doesn't exist
+    const notFoundSlug = useMemo(()=>{
+        if (routeState.contentType === 'endpoint' && routeState.contentId && collection) {
+            const request = findRequestById(collection, routeState.contentId);
+            if (!request) {
+                return `endpoint/${routeState.contentId}`;
+            }
+        }
+        return null;
+    }, [
+        routeState.contentType,
+        routeState.contentId,
+        collection
+    ]);
     // Prefill context for agent
     const { setPrefill } = usePlaygroundPrefill();
     // Playground navigation context for tab navigation
@@ -291,146 +455,36 @@ function DocsContent() {
     const { switchToDocs } = useModeContext();
     // Ref for the scrollable content area
     const contentRef = useRef(null);
-    // Update URL hash without triggering navigation
-    // Format: #tab or #tab/type/id (e.g., #api-reference, #api-reference/endpoint/123, #guides/page/quickstart)
-    const updateUrlHash = useCallback((hash, tab)=>{
-        const currentTab = tab || activeTab;
-        let newUrl;
-        if (!hash) {
-            // Just the tab
-            newUrl = `#${currentTab}`;
-        } else {
-            // Tab + path
-            newUrl = `#${currentTab}/${hash}`;
-        }
-        window.history.pushState(null, '', newUrl);
-    }, [
-        activeTab
-    ]);
-    // Navigate to hash - used for initial load and popstate
-    // Parse hash format: #tab or #tab/type/id
-    const parseHash = useCallback((hash)=>{
-        if (!hash) return {
-            tab: null,
-            type: null,
-            id: null
-        };
-        const parts = hash.split('/');
-        const tab = parts[0] || null;
-        const type = parts[1] || null;
-        const id = parts.slice(2).join('/') || null // Rejoin in case id has slashes
-        ;
-        return {
-            tab,
-            type,
-            id
-        };
-    }, []);
-    const navigateToHash = useCallback((collectionData)=>{
-        const hash = window.location.hash.slice(1) // Remove #
-        ;
-        if (!hash) {
-            // No hash - auto-select first endpoint
-            setSelectedDocSection(null);
-            setSelectedDocPage(null);
-            const firstEndpoint = getFirstEndpoint(collectionData);
-            if (firstEndpoint) {
-                setSelectedRequest(firstEndpoint);
-            } else {
-                setSelectedRequest(null);
-            }
-            return;
-        }
-        // Notes mode is handled by ModeContext, just clear API selection
-        if (hash === 'notes' || hash.startsWith('notes/')) {
-            setSelectedRequest(null);
-            setSelectedDocSection(null);
-            setSelectedDocPage(null);
-            return;
-        }
-        // Parse new format: #tab/type/id
-        const { tab, type, id } = parseHash(hash);
-        // Set the active tab if specified
-        if (tab) {
-            setActiveTab(tab);
-        }
-        // Handle legacy format (endpoint/xxx, page/xxx, doc/xxx without tab prefix)
-        const legacyType = hash.startsWith('endpoint/') ? 'endpoint' : hash.startsWith('page/') ? 'page' : hash.startsWith('doc/') ? 'doc' : null;
-        const actualType = type || legacyType;
-        const actualId = id || (legacyType ? hash.replace(`${legacyType}/`, '') : null);
-        if (actualType === 'endpoint' && actualId) {
-            const request = findRequestById(collectionData, actualId);
-            if (request) {
-                setSelectedRequest(request);
-                setSelectedDocSection(null);
-                setSelectedDocPage(null);
-                setNotFoundSlug(null);
-            } else {
-                // Endpoint not found - show 404 page
-                setSelectedRequest(null);
-                setSelectedDocSection(null);
-                setSelectedDocPage(null);
-                setNotFoundSlug(`endpoint/${actualId}`);
-            }
-        } else if (actualType === 'page' && actualId) {
-            setNotFoundSlug(null); // Clear not found state - DocPage handles its own 404
-            setSelectedDocPage(actualId);
-            setSelectedRequest(null);
-            setSelectedDocSection(null);
-        } else if (actualType === 'doc' && actualId) {
-            setSelectedDocSection(actualId);
-            setSelectedRequest(null);
-            setSelectedDocPage(null);
-            // Scroll to section after DOM update
-            setTimeout(()=>{
-                const element = document.getElementById(actualId);
-                if (element) {
-                    element.scrollIntoView({
-                        behavior: 'smooth',
-                        block: 'start'
-                    });
-                }
-            }, 100);
-        } else if (tab && !type) {
-            // Just a tab, no specific content - show default for that tab
-            setSelectedRequest(null);
-            setSelectedDocSection(null);
-            setSelectedDocPage(null);
-        }
-    }, [
-        parseHash
-    ]);
+    // Track if initial navigation has been done (prevents re-navigation on effect re-runs)
+    const hasInitialNavigated = useRef(false);
+    // Handle selecting a request - just navigates to URL
     const handleSelectRequest = useCallback((request)=>{
-        setSelectedRequest(request);
-        setSelectedDocSection(null);
-        setSelectedDocPage(null);
-        setNotFoundSlug(null); // Clear 404 state when selecting an endpoint
-        updateUrlHash(`endpoint/${request.id}`);
+        navigateToEndpoint(activeTab, request.id);
         // Reset tab navigation so the new endpoint can determine its default tab
         resetNavigation();
         // Switch to Docs mode to show endpoint documentation first
         switchToDocs();
     }, [
-        updateUrlHash,
+        activeTab,
         resetNavigation,
         switchToDocs
     ]);
+    // Handle selecting a documentation section (scroll to heading)
     const handleSelectDocumentation = useCallback((headingId)=>{
         const isIntro = headingId === 'introduction';
-        setSelectedDocSection(isIntro ? null : headingId);
-        setSelectedRequest(null);
-        setSelectedDocPage(null);
-        setNotFoundSlug(null); // Clear 404 state
-        updateUrlHash(isIntro ? '' : `doc/${headingId}`);
-        // Switch to Docs mode when selecting documentation
-        switchToDocs();
-        setTimeout(()=>{
-            if (isIntro) {
+        if (isIntro) {
+            // Scroll to top
+            navigateToTab(activeTab);
+            setTimeout(()=>{
                 contentRef.current?.scrollTo({
                     top: 0,
                     behavior: 'smooth'
                 });
-            } else {
+            }, 50);
+        } else {
+            // Navigate to section and scroll
+            navigateToSection(activeTab, headingId);
+            setTimeout(()=>{
                 const element = document.getElementById(headingId);
                 if (element) {
                     element.scrollIntoView({
@@ -438,12 +492,15 @@ function DocsContent() {
                         block: 'start'
                     });
                 }
-            }
-        }, 50);
+            }, 50);
+        }
+        // Switch to Docs mode when selecting documentation
+        switchToDocs();
     }, [
-        updateUrlHash,
+        activeTab,
         switchToDocs
     ]);
+    // Handle selecting a doc page
     const handleSelectDocPage = useCallback((slug)=>{
         // Find which tab this doc page belongs to
         let targetTab = activeTab;
@@ -488,13 +545,8 @@ function DocsContent() {
                 }
             }
         }
-        // Switch to the correct tab
-        setActiveTab(targetTab);
-        setSelectedDocPage(pageSlug);
-        setSelectedRequest(null);
-        setSelectedDocSection(null);
-        setNotFoundSlug(null); // Clear 404 state
-        updateUrlHash(`page/${pageSlug}`, targetTab);
+        // Navigate to the page via URL
+        navigateToPage(targetTab, pageSlug);
         switchToDocs();
         // Scroll to specific release if navigating to a changelog entry
         if (releaseSlug) {
@@ -529,7 +581,6 @@ function DocsContent() {
             }, 50);
         }
     }, [
-        updateUrlHash,
         switchToDocs,
         collection,
         activeTab
@@ -538,16 +589,15 @@ function DocsContent() {
     const handleApiVersionChange = useCallback((version)=>{
         if (version !== selectedApiVersion) {
             setSelectedApiVersion(version);
-            // Clear selected request when switching versions as endpoints may differ
-            setSelectedRequest(null);
-            setSelectedDocSection(null);
+            // Navigate to tab only (clears selection) when switching versions
+            navigateToTab(activeTab);
         }
     }, [
-        selectedApiVersion
+        selectedApiVersion,
+        activeTab
     ]);
     // Handle tab change from header
     const handleTabChange = useCallback((tabId)=>{
-        setActiveTab(tabId);
         // Reset mode to docs when switching tabs (exit sandbox/api-client mode)
         switchToDocs();
         // Find the tab config to check its type
@@ -555,68 +605,51 @@ function DocsContent() {
         const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || tabId === 'api-reference';
         if (tabId === 'changelog') {
             // Switch to Changelog tab
-            setSelectedDocPage(null);
-            setSelectedRequest(null);
-            setSelectedDocSection(null);
-            updateUrlHash('', tabId);
+            navigateToTab(tabId);
         } else if (isApiTab) {
             // API Reference or GraphQL tab
-            setSelectedDocSection(null);
             // Check if there are doc groups for this tab (MDX pages)
             const hasGroups = hasDocGroupsForTab(collection?.docGroups, tabId);
             if (hasGroups) {
                 // Has doc groups - select the first page from groups
                 const firstPage = getFirstDocPageForTab(collection?.docGroups, tabId);
                 if (firstPage) {
-                    setSelectedDocPage(firstPage);
-                    setSelectedRequest(null);
-                    updateUrlHash(`page/${firstPage}`, tabId);
+                    navigateToPage(tabId, firstPage);
                     switchToDocs();
                 } else {
                     // No pages in groups - auto-select first endpoint
-                    setSelectedDocPage(null);
                     const firstEndpoint = collection ? getFirstEndpoint(collection) : null;
                     if (firstEndpoint) {
-                        setSelectedRequest(firstEndpoint);
-                        updateUrlHash(`endpoint/${firstEndpoint.id}`, tabId);
+                        navigateToEndpoint(tabId, firstEndpoint.id);
                     } else {
-                        setSelectedRequest(null);
-                        updateUrlHash('', tabId);
+                        navigateToTab(tabId);
                     }
                 }
             } else {
                 // No doc groups - auto-select first endpoint
-                setSelectedDocPage(null);
                 const firstEndpoint = collection ? getFirstEndpoint(collection) : null;
                 if (firstEndpoint) {
-                    setSelectedRequest(firstEndpoint);
-                    updateUrlHash(`endpoint/${firstEndpoint.id}`, tabId);
+                    navigateToEndpoint(tabId, firstEndpoint.id);
                 } else {
-                    setSelectedRequest(null);
-                    updateUrlHash('', tabId);
+                    navigateToTab(tabId);
                 }
             }
         } else {
             // Switch to a doc group tab - find and select the first page in that tab
-            setSelectedRequest(null);
-            setSelectedDocSection(null);
             // Find the first doc group for this tab and select its first page
             if (collection?.docGroups) {
                 const tabDocGroup = collection.docGroups.find((g)=>isGroupForTab(g.id, tabId));
                 if (tabDocGroup && tabDocGroup.pages.length > 0) {
                     const firstPage = tabDocGroup.pages[0];
-                    setSelectedDocPage(firstPage.slug);
-                    updateUrlHash(`page/${firstPage.slug}`, tabId);
+                    navigateToPage(tabId, firstPage.slug);
                     switchToDocs();
                 } else {
-                    setSelectedDocPage(null);
-                    updateUrlHash('', tabId);
+                    navigateToTab(tabId);
                 }
             }
         }
     }, [
         collection,
-        updateUrlHash,
         switchToDocs
     ]);
     // Handler for agent navigation
@@ -624,19 +657,13 @@ function DocsContent() {
         if (!collection) return;
         const request = findRequestById(collection, endpointId);
         if (request) {
-            // Set the tab to API Reference first
-            setActiveTab('api-reference');
-            // Then set the selected request
-            setSelectedRequest(request);
-            setSelectedDocSection(null);
-            setSelectedDocPage(null);
-            updateUrlHash(`endpoint/${endpointId}`, 'api-reference');
+            // Navigate to the endpoint in api-reference tab
+            navigateToEndpoint('api-reference', endpointId);
             // Reset tab navigation so the new endpoint can determine its default tab
             resetNavigation();
         }
     }, [
         collection,
-        updateUrlHash,
         resetNavigation
     ]);
     // Handler for agent prefilling parameters
@@ -666,18 +693,7 @@ function DocsContent() {
     const clearExplainContext = useCallback(()=>{
         setExplainContext(null);
     }, []);
-    // Handle browser back/forward
-    useEffect(()=>{
-        if (!collection) return;
-        const handlePopState = ()=>{
-            navigateToHash(collection);
-        };
-        window.addEventListener('popstate', handlePopState);
-        return ()=>window.removeEventListener('popstate', handlePopState);
-    }, [
-        collection,
-        navigateToHash
-    ]);
+    // Note: Browser back/forward is now handled by useRouteState hook automatically
     // Dynamically set favicon from docs.json config
     useEffect(()=>{
         if (!collection?.docsFavicon) return;
@@ -733,184 +749,53 @@ function DocsContent() {
                 if (!selectedApiVersion && data?.selectedApiVersion) {
                     setSelectedApiVersion(data.selectedApiVersion);
                 }
-                // Only run initial navigation logic on first load, not on version changes
-                if (isInitialLoad) {
-                    // Set initial active tab from config (first tab) and select first item
-                    let initialTabId = 'api-reference';
-                    if (data?.navigationTabs && data.navigationTabs.length > 0) {
+                // Only run initial navigation logic on first load
+                if (isInitialLoad && !hasInitialNavigated.current) {
+                    hasInitialNavigated.current = true;
+                    // Helper: Navigate to first content for a given tab
+                    const navigateToFirstContent = (tabId)=>{
+                        const tabConfig = data.navigationTabs?.find((t)=>t.id === tabId);
+                        const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || tabId === 'api-reference';
+                        // Try doc pages first, then endpoints
+                        const firstPage = isApiTab ? getFirstDocPageForTab(data.docGroups, tabId) : data.docGroups?.find((g)=>isGroupForTab(g.id, tabId))?.pages[0]?.slug;
+                        if (firstPage) {
+                            navigateToPage(tabId, firstPage);
+                            return;
+                        }
+                        // Fall back to first endpoint for API tabs
+                        if (isApiTab) {
+                            const firstEndpoint = getFirstEndpoint(data);
+                            if (firstEndpoint) {
+                                navigateToEndpoint(tabId, firstEndpoint.id);
+                                return;
+                            }
+                        }
+                        // No content found, just navigate to tab
+                        navigateToTab(tabId);
+                    };
+                    // Get default tab (first tab in config)
+                    let defaultTabId = 'api-reference';
+                    if (data?.navigationTabs?.length > 0) {
                         const sortedTabs = [
                             ...data.navigationTabs
                         ].sort((a, b)=>a.order - b.order);
-                        initialTabId = sortedTabs[0].id;
-                        setActiveTab(initialTabId);
-                    }
-                    // Handle initial hash navigation after collection loads
-                    if (data) {
-                        // Use setTimeout to ensure state is set before navigation
-                        setTimeout(()=>{
-                            const hash = window.location.hash.slice(1);
-                            if (!hash) {
-                                // No hash - set URL to initial tab
-                                setSelectedDocSection(null);
-                                // Find the tab config to check its type
-                                const tabConfig = data.navigationTabs?.find((t)=>t.id === initialTabId);
-                                const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || initialTabId === 'api-reference';
-                                if (isApiTab) {
-                                    // API Reference or GraphQL tab
-                                    setSelectedDocSection(null);
-                                    // Check if there are doc groups for this tab (MDX pages)
-                                    const hasGroups = hasDocGroupsForTab(data.docGroups, initialTabId);
-                                    if (hasGroups) {
-                                        // Has doc groups - select the first page from groups
-                                        const firstPage = getFirstDocPageForTab(data.docGroups, initialTabId);
-                                        if (firstPage) {
-                                            setSelectedDocPage(firstPage);
-                                            setSelectedRequest(null);
-                                            updateUrlHash(`page/${firstPage}`, initialTabId);
-                                        } else {
-                                            // No pages in groups - auto-select first endpoint
-                                            setSelectedDocPage(null);
-                                            const firstEndpoint = getFirstEndpoint(data);
-                                            if (firstEndpoint) {
-                                                setSelectedRequest(firstEndpoint);
-                                                updateUrlHash(`endpoint/${firstEndpoint.id}`, initialTabId);
-                                            } else {
-                                                setSelectedRequest(null);
-                                                updateUrlHash('', initialTabId);
-                                            }
-                                        }
-                                    } else {
-                                        // No doc groups - auto-select first endpoint
-                                        setSelectedDocPage(null);
-                                        const firstEndpoint = getFirstEndpoint(data);
-                                        if (firstEndpoint) {
-                                            setSelectedRequest(firstEndpoint);
-                                            updateUrlHash(`endpoint/${firstEndpoint.id}`, initialTabId);
-                                        } else {
-                                            setSelectedRequest(null);
-                                            updateUrlHash('', initialTabId);
-                                        }
-                                    }
-                                    switchToDocs();
-                                } else {
-                                    // Doc group tab - select first page
-                                    setSelectedRequest(null);
-                                    const tabDocGroup = data.docGroups?.find((g)=>isGroupForTab(g.id, initialTabId));
-                                    if (tabDocGroup && tabDocGroup.pages.length > 0) {
-                                        const firstPage = tabDocGroup.pages[0];
-                                        setSelectedDocPage(firstPage.slug);
-                                        updateUrlHash(`page/${firstPage.slug}`, initialTabId);
-                                        switchToDocs();
-                                    } else {
-                                        setSelectedDocPage(null);
-                                        updateUrlHash('', initialTabId);
-                                        switchToDocs();
-                                    }
-                                }
-                            } else if (hash === 'notes' || hash.startsWith('notes/')) {
-                                // Notes mode - handled by ModeContext, just clear API selection
-                                setSelectedRequest(null);
-                                setSelectedDocSection(null);
-                            } else {
-                                // Parse the hash to get tab and content info
-                                // Format: #tab or #tab/type/id (e.g., #api-reference/endpoint/123)
-                                const parts = hash.split('/');
-                                const hashTab = parts[0];
-                                const hashType = parts[1];
-                                const hashId = parts.slice(2).join('/');
-                                // Set the tab from the hash
-                                if (hashTab && data.navigationTabs?.some((t)=>t.id === hashTab)) {
-                                    setActiveTab(hashTab);
-                                }
-                                // Handle legacy format (endpoint/xxx without tab prefix)
-                                const isLegacyFormat = hash.startsWith('endpoint/') || hash.startsWith('page/') || hash.startsWith('doc/');
-                                const actualType = isLegacyFormat ? parts[0] : hashType;
-                                const actualId = isLegacyFormat ? parts.slice(1).join('/') : hashId;
-                                if (actualType === 'endpoint' && actualId) {
-                                    const request = findRequestById(data, actualId);
-                                    if (request) {
-                                        setSelectedRequest(request);
-                                        setSelectedDocSection(null);
-                                        setSelectedDocPage(null);
-                                        switchToDocs();
-                                        return;
-                                    } else {
-                                        setSelectedRequest(null);
-                                        setSelectedDocSection(null);
-                                        setSelectedDocPage(null);
-                                        switchToDocs();
-                                    }
-                                } else if (actualType === 'page' && actualId) {
-                                    setSelectedDocPage(actualId);
-                                    setSelectedRequest(null);
-                                    setSelectedDocSection(null);
-                                    switchToDocs();
-                                } else if (actualType === 'doc' && actualId) {
-                                    setSelectedDocSection(actualId);
-                                    setSelectedRequest(null);
-                                    setSelectedDocPage(null);
-                                    switchToDocs();
-                                    setTimeout(()=>{
-                                        const element = document.getElementById(actualId);
-                                        if (element) {
-                                            element.scrollIntoView({
-                                                behavior: 'smooth',
-                                                block: 'start'
-                                            });
-                                        }
-                                    }, 100);
-                                } else if (hashTab && !hashType) {
-                                    // Just a tab, show its default content
-                                    setSelectedDocSection(null);
-                                    // Check if this is an API tab
-                                    const tabConfig = data.navigationTabs?.find((t)=>t.id === hashTab);
-                                    const isApiTab = tabConfig?.type === 'openapi' || tabConfig?.type === 'graphql' || hashTab === 'api-reference';
-                                    if (isApiTab) {
-                                        // Check if there are doc groups for this tab (MDX pages)
-                                        const hasGroups = hasDocGroupsForTab(data.docGroups, hashTab);
-                                        if (hasGroups) {
-                                            // Has doc groups - select the first page from groups
-                                            const firstPage = getFirstDocPageForTab(data.docGroups, hashTab);
-                                            if (firstPage) {
-                                                setSelectedDocPage(firstPage);
-                                                setSelectedRequest(null);
-                                                updateUrlHash(`page/${firstPage}`, hashTab);
-                                            } else {
-                                                // No pages in groups - auto-select first endpoint
-                                                setSelectedDocPage(null);
-                                                const firstEndpoint = getFirstEndpoint(data);
-                                                if (firstEndpoint) {
-                                                    setSelectedRequest(firstEndpoint);
-                                                    updateUrlHash(`endpoint/${firstEndpoint.id}`, hashTab);
-                                                } else {
-                                                    setSelectedRequest(null);
-                                                }
-                                            }
-                                        } else {
-                                            // No doc groups - auto-select first endpoint
-                                            setSelectedDocPage(null);
-                                            const firstEndpoint = getFirstEndpoint(data);
-                                            if (firstEndpoint) {
-                                                setSelectedRequest(firstEndpoint);
-                                                updateUrlHash(`endpoint/${firstEndpoint.id}`, hashTab);
-                                            } else {
-                                                setSelectedRequest(null);
-                                            }
-                                        }
-                                    } else {
-                                        setSelectedDocPage(null);
-                                        setSelectedRequest(null);
-                                    }
-                                    switchToDocs();
-                                }
-                            }
-                        }, 0);
+                        defaultTabId = sortedTabs[0].id;
                     }
-                } else {
-                    // Version change - clear selected endpoint as it may not exist in the new version
-                    setSelectedRequest(null);
-                    setSelectedDocSection(null);
+                    // Handle initial navigation after collection loads
+                    setTimeout(()=>{
+                        const hash = window.location.hash.slice(1);
+                        const isTabOnly = hash && !hash.includes('/');
+                        if (!hash) {
+                            // No hash - navigate to first content of default tab
+                            navigateToFirstContent(defaultTabId);
+                        } else if (isTabOnly) {
+                            // Just a tab name (e.g., #guides) - navigate to first content
+                            navigateToFirstContent(hash);
+                        }
+                    // View mode (docs/playground/notes) is derived from URL by ModeProvider
+                    }, 0);
                 }
+            // Version changes are handled by handleApiVersionChange callback
             } catch (err) {
                 console.error('Error fetching collection:', err);
                 setError(err instanceof Error ? err.message : 'Failed to load API documentation');
@@ -922,7 +807,6 @@ function DocsContent() {
         fetchCollection();
     // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
-        switchToDocs,
         selectedApiVersion
     ]);
     // Only show full-page loading on initial load
@@ -1165,10 +1049,29 @@ function ModeToggleTabs({ hasEndpoint }) {
 function DocsWithMode({ collection, selectedRequest, selectedDocSection, selectedDocPage, activeTab, onTabChange, contentRef, showAuthModal, setShowAuthModal, handleSelectRequest, handleSelectDocumentation, handleSelectDocPage, handleDebugRequest, handleExplainRequest, handleAgentNavigate, handleAgentPrefill, debugContext, clearDebugContext, explainContext, clearExplainContext, navigateAndHighlight, selectedApiVersion, handleApiVersionChange, isVersionLoading, notFoundSlug }) {
     const { mode, switchToDocs } = useModeContext();
     const { setTheme } = useTheme();
+    // Agent panel state - controls popup button and push animation
+    const { isRightSidebarOpen, openRightSidebar } = useMobile();
+    // Build endpoint index for suggestions (memoized)
+    const endpointIndex = useMemo(()=>buildEndpointIndex(collection), [
+        collection
+    ]);
     // GraphQL state
     const [graphqlOperations, setGraphqlOperations] = useState([]);
     const [graphqlCollection, setGraphqlCollection] = useState(null);
-    const [selectedGraphQLOperation, setSelectedGraphQLOperation] = useState(null);
+    const [graphqlSchemaSDL, setGraphqlSchemaSDL] = useState(undefined);
+    // Use route state for URL-based selection
+    const routeState = useRouteState();
+    // Derive selected GraphQL operation from URL
+    const selectedGraphQLOperation = useMemo(()=>{
+        if (routeState.contentType !== 'endpoint' || !routeState.contentId) {
+            return null;
+        }
+        return graphqlOperations.find((op)=>op.id === routeState.contentId) || null;
+    }, [
+        routeState.contentType,
+        routeState.contentId,
+        graphqlOperations
+    ]);
     // Get API spec URL from environment or collection
     const apiSpecUrl = process.env.NEXT_PUBLIC_OPENAPI_URL || collection.name || 'default';
     // Check if there are endpoints
@@ -1193,7 +1096,7 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
     }, []);
     // Wrap agent navigate to switch to Docs mode and navigate to endpoint
     const handleAgentNavigateWithModeSwitch = useCallback((endpointId)=>{
-        // Just navigate - handleAgentNavigate already sets the tab via setActiveTab
+        // handleAgentNavigate navigates via URL
         handleAgentNavigate(endpointId);
     }, [
         handleAgentNavigate
@@ -1222,22 +1125,29 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
         if (!showGraphQL || !schemaPath) {
             setGraphqlOperations([]);
             setGraphqlCollection(null);
-            setSelectedGraphQLOperation(null); // Clear selection when leaving GraphQL tab
+            setGraphqlSchemaSDL(undefined);
             return;
         }
         // Load and parse GraphQL schema
         const loadGraphQLSchema = async ()=>{
             try {
+                console.log('[DocsViewer] Loading GraphQL schema from:', schemaPath);
                 const response = await fetch(`/api/schema?path=${encodeURIComponent(schemaPath)}`);
-                if (!response.ok) return;
+                if (!response.ok) {
+                    console.error('[DocsViewer] Failed to fetch schema:', response.status);
+                    return;
+                }
                 const schemaContent = await response.text();
+                console.log('[DocsViewer] Schema loaded, length:', schemaContent.length);
+                setGraphqlSchemaSDL(schemaContent); // Store schema SDL for autocomplete
                 const operations = parseGraphQLSchema(schemaContent);
+                console.log('[DocsViewer] Parsed operations:', operations.length);
                 setGraphqlOperations(operations);
                 // Convert to BrainfishCollection for sidebar
                 const gqlCollection = convertGraphQLToCollection(operations, schemaEndpoint || '');
                 setGraphqlCollection(gqlCollection);
             } catch (err) {
-                console.error('Failed to load GraphQL schema:', err);
+                console.error('[DocsViewer] Failed to load GraphQL schema:', err);
             }
         };
         loadGraphQLSchema();
@@ -1246,58 +1156,34 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
         schemaPath,
         schemaEndpoint
     ]);
-    // Auto-select GraphQL operation from URL hash or default to first operation
+    // Auto-navigate to first GraphQL operation when none selected and no doc pages
     useEffect(()=>{
         if (!showGraphQL || graphqlOperations.length === 0) {
             return;
         }
-        // Check if there's a selection in the URL hash first
-        const hash = window.location.hash.slice(1) // Remove #
-        ;
-        if (hash) {
-            const parts = hash.split('/');
-            const hashType = parts[1];
-            const hashId = parts.slice(2).join('/');
-            if (hashType === 'endpoint' && hashId) {
-                // Try to find and select the operation from the URL hash
-                const operation = graphqlOperations.find((op)=>op.id === hashId);
-                if (operation) {
-                    setSelectedGraphQLOperation(operation);
-                    return;
-                }
-            }
-        }
-        // If already have a selection, don't override it
-        if (selectedGraphQLOperation) {
+        // If there's already content selected (page or endpoint), don't auto-navigate
+        if (routeState.contentType) {
             return;
         }
-        // Check if there are doc groups for this tab first
+        // Check if there are doc groups for this tab
         const hasGroups = hasDocGroupsForTab(collection?.docGroups, activeTab);
         if (!hasGroups) {
-            // No doc groups - auto-select first GraphQL operation
+            // No doc groups - auto-navigate to first GraphQL operation
             const firstOperation = graphqlOperations[0];
-            setSelectedGraphQLOperation(firstOperation);
-            window.history.pushState(null, '', `#${activeTab}/endpoint/${firstOperation.id}`);
+            navigateToEndpoint(activeTab, firstOperation.id);
         }
     }, [
         showGraphQL,
         graphqlOperations,
-        selectedGraphQLOperation,
         activeTab,
-        collection?.docGroups
+        collection?.docGroups,
+        routeState.contentType
     ]);
-    // Handle GraphQL operation selection from sidebar
+    // Handle GraphQL operation selection from sidebar - just navigates via URL
     const handleSelectGraphQLOperation = useCallback((request)=>{
-        // Find the matching GraphQL operation
-        const operation = graphqlOperations.find((op)=>op.id === request.id);
-        if (operation) {
-            setSelectedGraphQLOperation(operation);
-            // Update URL hash
-            window.history.pushState(null, '', `#${activeTab}/endpoint/${request.id}`);
-            switchToDocs();
-        }
+        navigateToEndpoint(activeTab, request.id);
+        switchToDocs();
     }, [
-        graphqlOperations,
         activeTab,
         switchToDocs
     ]);
@@ -1381,7 +1267,8 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
                 docsNavbar: collection.docsNavbar
             }),
             /*#__PURE__*/ _jsxs("div", {
-                className: "docs-layout flex flex-1 overflow-hidden relative z-0 min-h-0",
+                className: cn("docs-layout flex flex-1 overflow-hidden relative z-0 min-h-0", "transition-[margin] duration-300 ease-in-out", // Push content left when agent panel is open (only on larger screens)
+                isRightSidebarOpen && "lg:mr-96"),
                 children: [
                     !showChangelog && /*#__PURE__*/ _jsx(DocsSidebar, {
                         collection: {
@@ -1426,8 +1313,8 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
                                 activeTab: activeTab,
                                 children: /*#__PURE__*/ _jsx("div", {
                                     ref: contentRef,
-                                    className: cn("docs-content-area flex-1 bg-background min-w-0", showChangelog || showGraphQL && selectedGraphQLOperation ? "overflow-hidden flex flex-col" : "overflow-y-auto scroll-smooth"),
-                                    children: showGraphQL && selectedGraphQLOperation ? /*#__PURE__*/ _jsx("div", {
+                                    className: cn("docs-content-area flex-1 bg-background min-w-0", showChangelog || showGraphQL && selectedGraphQLOperation && !selectedDocPage ? "overflow-hidden flex flex-col" : "overflow-y-auto scroll-smooth"),
+                                    children: showGraphQL && selectedGraphQLOperation && !selectedDocPage ? /*#__PURE__*/ _jsx("div", {
                                         className: "flex-1 flex flex-col h-full",
                                         children: /*#__PURE__*/ _jsx(GraphQLPlayground, {
                                             endpoint: activeGraphQLSchemas[0]?.endpoint || '',
@@ -1436,7 +1323,8 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
                                             selectedOperationId: selectedGraphQLOperation?.id,
                                             hideExplorer: true,
                                             headers: {},
-                                            theme: "dark"
+                                            theme: "dark",
+                                            schemaSDL: graphqlSchemaSDL
                                         })
                                     }) : showChangelog ? /*#__PURE__*/ _jsx(ChangelogPage, {
                                         releases: collection.changelogReleases || [],
@@ -1534,6 +1422,14 @@ function DocsWithMode({ collection, selectedRequest, selectedDocSection, selecte
             /*#__PURE__*/ _jsx(GlobalAuthModal, {
                 open: showAuthModal,
                 onClose: ()=>setShowAuthModal(false)
+            }),
+            !isRightSidebarOpen && /*#__PURE__*/ _jsx(AgentPopupButton, {
+                onClick: openRightSidebar,
+                currentEndpoint: selectedRequest ? {
+                    id: selectedRequest.id,
+                    name: selectedRequest.name
+                } : null,
+                endpointIndex: endpointIndex
             })
         ]
     });