@brainfish-ai/devdoc 0.1.43 → 0.1.44

package/renderer/lib/api-docs/code-editor/mode-context.js

@@ -1,114 +1,86 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { createContext, useContext, useState, useCallback, useEffect, useRef } from 'react';
+import React, { createContext, useContext, useState, useCallback, useEffect, useMemo } from 'react';
+import { switchView } from '@/lib/docs-navigation';
 const ModeContext = /*#__PURE__*/ createContext(null);
-// Helper to parse notes path from URL hash
-function parseNotesHash() {
-    if (typeof window === 'undefined') return {
-        isNotes: false,
-        filePath: null
-    };
-    const hash = window.location.hash.slice(1) // Remove #
-    ;
-    if (hash === 'notes') {
-        return {
-            isNotes: true,
-            filePath: null
-        };
-    }
-    if (hash.startsWith('notes/')) {
-        // Decode any encoded characters but path should mostly be plain text
-        const filePath = decodeURIComponent(hash.slice(6)) // Remove 'notes/'
-        ;
-        return {
-            isNotes: true,
-            filePath: filePath || null
-        };
+/**
+ * Parse view mode from URL hash
+ */ function parseViewFromHash() {
+    if (typeof window === 'undefined') return 'docs';
+    const hash = window.location.hash.slice(1);
+    if (!hash) return 'docs';
+    // Check for view suffix at the end
+    if (hash.endsWith('/playground')) return 'playground';
+    if (hash.endsWith('/notes')) return 'notes';
+    return 'docs';
+}
+/**
+ * Convert ViewMode to PlaygroundMode
+ */ function viewToPlaygroundMode(view) {
+    switch(view){
+        case 'playground':
+            return 'api_client';
+        case 'notes':
+            return 'notes';
+        default:
+            return 'docs';
     }
-    return {
-        isNotes: false,
-        filePath: null
-    };
 }
-// Helper to update URL hash for notes
-// Only encode special chars that would break the URL, keep slashes readable
-function updateNotesHash(filePath) {
-    if (typeof window === 'undefined') return;
-    const newHash = filePath ? `#notes/${filePath.replace(/#/g, '%23').replace(/\?/g, '%3F')}` : '#notes';
-    window.history.pushState(null, '', newHash);
+/**
+ * Convert PlaygroundMode to ViewMode
+ */ function playgroundModeToView(mode) {
+    switch(mode){
+        case 'api_client':
+            return 'playground';
+        case 'notes':
+            return 'notes';
+        default:
+            return 'docs';
+    }
 }
 export function ModeProvider({ children, defaultMode = 'docs' }) {
-    const [mode, setMode] = useState(defaultMode);
+    // Track current hash to derive mode
+    const [hash, setHash] = useState(()=>typeof window !== 'undefined' ? window.location.hash : '');
+    // Derive mode from URL hash
+    const mode = useMemo(()=>{
+        const view = parseViewFromHash();
+        return viewToPlaygroundMode(view);
+    }, [
+        hash
+    ]);
+    // Notes-specific state (not URL-based yet)
     const [activeFilePath, setActiveFilePathState] = useState(null);
     const [streamingContent, setStreamingContent] = useState(null);
     const [notesRefreshTrigger, setNotesRefreshTrigger] = useState(0);
-    // Use ref to track mode for callbacks (avoids stale closure issues)
-    const modeRef = useRef(defaultMode);
-    // Keep ref in sync with state
-    useEffect(()=>{
-        modeRef.current = mode;
-    }, [
-        mode
-    ]);
-    // Initialize from URL hash on mount
-    useEffect(()=>{
-        const { isNotes, filePath } = parseNotesHash();
-        if (isNotes) {
-            setMode('notes');
-            modeRef.current = 'notes';
-            setActiveFilePathState(filePath);
-        }
-    }, []);
-    // Handle browser back/forward navigation
+    // Listen for hash changes to update mode
     useEffect(()=>{
-        const handlePopState = ()=>{
-            const { isNotes, filePath } = parseNotesHash();
-            if (isNotes) {
-                setMode('notes');
-                modeRef.current = 'notes';
-                setActiveFilePathState(filePath);
-            } else {
-                // Default to docs mode when no notes hash
-                setMode('docs');
-                modeRef.current = 'docs';
-            }
+        const handleHashChange = ()=>{
+            setHash(window.location.hash);
+        };
+        window.addEventListener('hashchange', handleHashChange);
+        window.addEventListener('popstate', handleHashChange);
+        return ()=>{
+            window.removeEventListener('hashchange', handleHashChange);
+            window.removeEventListener('popstate', handleHashChange);
         };
-        window.addEventListener('popstate', handlePopState);
-        return ()=>window.removeEventListener('popstate', handlePopState);
     }, []);
-    // Wrapper for setActiveFilePath that also updates URL
+    // Wrapper for setActiveFilePath
     const setActiveFilePath = useCallback((path)=>{
         // Handle the ?t= timestamp suffix for forcing reloads
         const cleanPath = path?.split('?')[0] || null;
         setActiveFilePathState(cleanPath);
-        // Update URL if we're in notes mode (use ref to avoid stale closure)
-        if (modeRef.current === 'notes') {
-            updateNotesHash(cleanPath);
-        }
-    }, []) // No dependencies - uses ref
-    ;
+    }, []);
     const switchToNotes = useCallback((openFile)=>{
-        const filePath = openFile || null;
-        setActiveFilePathState(filePath);
-        setMode('notes');
-        modeRef.current = 'notes';
-        updateNotesHash(filePath);
+        if (openFile) {
+            setActiveFilePathState(openFile);
+        }
+        switchView('notes');
     }, []);
     const switchToApiClient = useCallback(()=>{
-        setMode('api_client');
-        modeRef.current = 'api_client';
-    // Don't update URL here - let the main API docs component handle it
+        switchView('playground');
     }, []);
     const switchToDocs = useCallback(()=>{
-        setMode('docs');
-        modeRef.current = 'docs';
-        // Only clear the hash if it's a notes hash, preserve doc/endpoint hashes
-        if (typeof window !== 'undefined') {
-            const hash = window.location.hash.slice(1);
-            if (hash === 'notes' || hash.startsWith('notes/')) {
-                window.history.pushState(null, '', window.location.pathname + window.location.search);
-            }
-        }
+        switchView('docs');
     }, []);
     const appendStreamingContent = useCallback((delta)=>{
         setStreamingContent((prev)=>{

package/renderer/lib/api-docs/mobile-context.js

@@ -1,11 +1,29 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useState, useCallback, useEffect } from 'react';
+const AGENT_ASSIST_STORAGE_KEY = 'devdoc-agent-assist-open';
 const MobileContext = /*#__PURE__*/ createContext(null);
+// Helper to get initial state from localStorage (default to true)
+function getInitialAgentAssistState() {
+    if (typeof window === 'undefined') return true;
+    const stored = localStorage.getItem(AGENT_ASSIST_STORAGE_KEY);
+    // Default to true (open) if not set
+    return stored === null ? true : stored === 'true';
+}
 export function MobileProvider({ children }) {
     const [isLeftSidebarOpen, setIsLeftSidebarOpen] = useState(false);
     const [isRightSidebarOpen, setIsRightSidebarOpen] = useState(false);
     const [isMobile, setIsMobile] = useState(false);
+    const [isHydrated, setIsHydrated] = useState(false);
+    // Initialize from localStorage after hydration (only on desktop)
+    useEffect(()=>{
+        const isMobileView = window.innerWidth < 1024;
+        if (!isMobileView) {
+            const savedState = getInitialAgentAssistState();
+            setIsRightSidebarOpen(savedState);
+        }
+        setIsHydrated(true);
+    }, []);
     // Detect mobile on mount and window resize
     useEffect(()=>{
         const checkMobile = ()=>{
@@ -17,11 +35,11 @@ export function MobileProvider({ children }) {
         window.addEventListener('resize', checkMobile);
         return ()=>window.removeEventListener('resize', checkMobile);
     }, []);
-    // Close sidebars when switching to desktop
+    // Close left sidebar when switching to desktop (left sidebar is mobile-only)
+    // Note: Right sidebar can stay open on desktop as it's now a toggleable panel
     useEffect(()=>{
         if (!isMobile) {
             setIsLeftSidebarOpen(false);
-            setIsRightSidebarOpen(false);
         }
     }, [
         isMobile
@@ -32,7 +50,14 @@ export function MobileProvider({ children }) {
         setIsRightSidebarOpen(false);
     }, []);
     const toggleRightSidebar = useCallback(()=>{
-        setIsRightSidebarOpen((prev)=>!prev);
+        setIsRightSidebarOpen((prev)=>{
+            const newState = !prev;
+            // Persist to localStorage (only on desktop)
+            if (typeof window !== 'undefined' && window.innerWidth >= 1024) {
+                localStorage.setItem(AGENT_ASSIST_STORAGE_KEY, String(newState));
+            }
+            return newState;
+        });
         // Close left sidebar when opening right
         setIsLeftSidebarOpen(false);
     }, []);
@@ -46,13 +71,25 @@ export function MobileProvider({ children }) {
     const openRightSidebar = useCallback(()=>{
         setIsRightSidebarOpen(true);
         setIsLeftSidebarOpen(false);
+        // Persist to localStorage (only on desktop)
+        if (typeof window !== 'undefined' && window.innerWidth >= 1024) {
+            localStorage.setItem(AGENT_ASSIST_STORAGE_KEY, 'true');
+        }
     }, []);
     const closeRightSidebar = useCallback(()=>{
         setIsRightSidebarOpen(false);
+        // Persist to localStorage (only on desktop)
+        if (typeof window !== 'undefined' && window.innerWidth >= 1024) {
+            localStorage.setItem(AGENT_ASSIST_STORAGE_KEY, 'false');
+        }
     }, []);
     const closeAllSidebars = useCallback(()=>{
         setIsLeftSidebarOpen(false);
         setIsRightSidebarOpen(false);
+        // Persist to localStorage (only on desktop)
+        if (typeof window !== 'undefined' && window.innerWidth >= 1024) {
+            localStorage.setItem(AGENT_ASSIST_STORAGE_KEY, 'false');
+        }
     }, []);
     return /*#__PURE__*/ _jsx(MobileContext.Provider, {
         value: {

package/renderer/lib/docs/config/environment.js

@@ -0,0 +1,38 @@
+/**
+ * Environment Detection Utilities
+ * 
+ * Utilities for detecting development vs production environment
+ * Used for visibility filtering of private documentation content
+ */ /**
+ * Check if the application is running in development mode
+ * 
+ * Development mode is determined by:
+ * 1. NODE_ENV !== 'production'
+ * 2. DEVDOC_DEV_MODE env var is set to 'true' (set by devdoc dev command)
+ * 
+ * @returns true if in development mode, false if in production
+ */ export function isDevMode() {
+    return process.env.NODE_ENV !== 'production' || process.env.DEVDOC_DEV_MODE === 'true';
+}
+/**
+ * Check if the application is running in production mode
+ * 
+ * @returns true if in production mode, false if in development
+ */ export function isProductionMode() {
+    return !isDevMode();
+}
+/**
+ * Check if an item should be visible based on its visibility setting
+ * 
+ * @param visibility - The visibility setting ('public', 'private', or undefined)
+ * @param devMode - Whether we're in development mode (defaults to isDevMode())
+ * @returns true if the item should be shown, false if it should be hidden
+ */ export function shouldShowItem(visibility, devMode) {
+    const isDev = devMode ?? isDevMode();
+    // Private items are only visible in dev mode
+    if (visibility === 'private') {
+        return isDev;
+    }
+    // Public or undefined visibility = always show
+    return true;
+}

package/renderer/lib/docs/config/index.js

@@ -3,3 +3,4 @@
  */ export { docsConfigSchema, parseDocsConfig, safeParseDocsConfig, getDefaultDocsConfig } from './schema';
 export { domainConfigSchema, parseDomainConfig, safeParseDomainConfig, isValidDomain, normalizeDomain, getDnsInstructions } from './domain-schema';
 export { loadDocsConfig, safeLoadDocsConfig, clearConfigCache, hasDocsConfig, getContentDir, resolvePagePath, loadPageContent, listMdxFiles } from './loader';
+export { isDevMode, isProductionMode, shouldShowItem } from './environment';

package/renderer/lib/docs/config/schema.js

@@ -15,6 +15,13 @@ const navLinkSchema = z.object({
     label: z.string(),
     href: z.string()
 });
+// Visibility schema for tabs, groups, and pages
+// - 'public': Always visible (default)
+// - 'private': Only visible in development mode, hidden in production
+const visibilitySchema = z.enum([
+    'public',
+    'private'
+]).optional();
 // Page can be a string or a nested group
 const pageRefSchema = z.lazy(()=>z.union([
         z.string(),
@@ -29,7 +36,8 @@ const pageRefSchema = z.lazy(()=>z.union([
 const groupSchema = z.object({
     group: z.string(),
     pages: z.array(pageRefSchema),
-    icon: z.string().optional()
+    icon: z.string().optional(),
+    visibility: visibilitySchema
 });
 // OpenAPI version schema
 const openapiVersionSchema = z.object({
@@ -41,7 +49,8 @@ const openapiVersionSchema = z.object({
 const docsTabSchema = z.object({
     tab: z.string(),
     type: z.literal('docs').optional(),
-    groups: z.array(groupSchema)
+    groups: z.array(groupSchema),
+    visibility: visibilitySchema
 });
 const openapiTabSchema = z.object({
     tab: z.string(),
@@ -49,7 +58,8 @@ const openapiTabSchema = z.object({
     path: z.string().optional(),
     versions: z.array(openapiVersionSchema).optional(),
     spec: z.string().optional(),
-    groups: z.array(groupSchema).optional()
+    groups: z.array(groupSchema).optional(),
+    visibility: visibilitySchema
 });
 const graphqlTabSchema = z.object({
     tab: z.string(),
@@ -57,12 +67,14 @@ const graphqlTabSchema = z.object({
     path: z.string().optional(),
     schema: z.string(),
     endpoint: z.string().optional(),
-    groups: z.array(groupSchema).optional()
+    groups: z.array(groupSchema).optional(),
+    visibility: visibilitySchema
 });
 const changelogTabSchema = z.object({
     tab: z.string(),
     type: z.literal('changelog'),
-    path: z.string().optional()
+    path: z.string().optional(),
+    visibility: visibilitySchema
 });
 const tabSchema = z.union([
     docsTabSchema,

package/renderer/lib/docs/mdx/compiler.js

@@ -4,6 +4,7 @@ import rehypeSlug from 'rehype-slug';
 import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 import remarkGfm from 'remark-gfm';
 import { parseFrontmatter, safeParseFrontmatter } from './frontmatter';
+import { remarkMermaid } from './remark-mermaid';
 /**
  * Extract frontmatter from raw MDX content
  */ export function extractFrontmatter(source) {
@@ -50,7 +51,8 @@ import { parseFrontmatter, safeParseFrontmatter } from './frontmatter';
             parseFrontmatter: false,
             mdxOptions: {
                 remarkPlugins: [
-                    remarkGfm
+                    remarkGfm,
+                    remarkMermaid
                 ],
                 rehypePlugins: [
                     rehypeSlug,
@@ -85,7 +87,8 @@ import { parseFrontmatter, safeParseFrontmatter } from './frontmatter';
             parseFrontmatter: false,
             mdxOptions: {
                 remarkPlugins: [
-                    remarkGfm
+                    remarkGfm,
+                    remarkMermaid
                 ],
                 rehypePlugins: [
                     rehypeSlug

package/renderer/lib/docs/mdx/index.js

@@ -6,3 +6,5 @@
 export { compileMDXContent, quickCompileMDX, validateMDXContent, extractFrontmatter, extractHeadings } from './compiler';
 // Frontmatter
 export { frontmatterSchema, parseFrontmatter, safeParseFrontmatter, getDefaultFrontmatter } from './frontmatter';
+// Remark plugins
+export { remarkMermaid } from './remark-mermaid';

package/renderer/lib/docs/mdx/remark-mermaid.js

@@ -0,0 +1,63 @@
+import { visit } from 'unist-util-visit';
+/**
+ * Remark plugin to transform mermaid code blocks into Mermaid components
+ * 
+ * Transforms:
+ * ```mermaid
+ * flowchart LR
+ *     A --> B
+ * ```
+ * 
+ * Into:
+ * <Mermaid>
+ * {`flowchart LR
+ *     A --> B`}
+ * </Mermaid>
+ */ export function remarkMermaid() {
+    return (tree)=>{
+        visit(tree, 'code', (node, index, parent)=>{
+            if (node.lang !== 'mermaid' || !parent || index === undefined) {
+                return;
+            }
+            // Replace the code block with MDX JSX element
+            const mermaidNode = {
+                type: 'mdxJsxFlowElement',
+                name: 'Mermaid',
+                attributes: [],
+                children: [
+                    {
+                        type: 'mdxFlowExpression',
+                        value: '`' + node.value + '`',
+                        data: {
+                            estree: {
+                                type: 'Program',
+                                body: [
+                                    {
+                                        type: 'ExpressionStatement',
+                                        expression: {
+                                            type: 'TemplateLiteral',
+                                            expressions: [],
+                                            quasis: [
+                                                {
+                                                    type: 'TemplateElement',
+                                                    value: {
+                                                        raw: node.value,
+                                                        cooked: node.value
+                                                    },
+                                                    tail: true
+                                                }
+                                            ]
+                                        }
+                                    }
+                                ],
+                                sourceType: 'module'
+                            }
+                        }
+                    }
+                ]
+            };
+            // Replace the code node with the Mermaid component
+            parent.children.splice(index, 1, mermaidNode);
+        });
+    };
+}

package/renderer/lib/docs/navigation/index.js

@@ -1,4 +1,3 @@
 /**
  * Navigation Module Exports
- */ export * from './types';
-export { generateNavigation, findPageNavContext, getAllPagePaths, loadPageMeta } from './generator';
+ */ export { generateNavigation, findPageNavContext, getAllPagePaths, loadPageMeta } from './generator';

package/renderer/lib/docs/navigation/types.js

@@ -3,7 +3,9 @@
  * 
  * Types for the documentation navigation system
  */ /**
- * A navigation item representing a single page
+ * Visibility type for navigation items
+ * - 'public': Always visible (default)
+ * - 'private': Only visible in development mode, hidden in production
  */ /**
  * Page metadata for navigation
  */ export { };

package/renderer/lib/docs-navigation.js

@@ -0,0 +1,140 @@
+/**
+ * Navigation utilities for docs viewer
+ * 
+ * These functions provide simple URL updates without state management.
+ * The URL is the single source of truth - components derive their state from the URL.
+ * 
+ * URL Schema:
+ * - #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)
+ */ /**
+ * Navigate to a documentation page
+ * @param tab - Tab ID (e.g., 'guides', 'graphql-api')
+ * @param slug - Page slug (e.g., 'graphql/introduction')
+ * @param view - View mode (docs, playground, notes). Defaults to 'docs'
+ */ export function navigateToPage(tab, slug, view) {
+    const viewSuffix = view && view !== 'docs' ? `/${view}` : '';
+    window.location.hash = `${tab}/page/${slug}${viewSuffix}`;
+}
+/**
+ * Navigate to an API endpoint or GraphQL operation
+ * @param tab - Tab ID (e.g., 'api-reference', 'graphql-api')
+ * @param id - Endpoint ID
+ * @param view - View mode (docs, playground, notes). Defaults to 'docs'
+ */ export function navigateToEndpoint(tab, id, view) {
+    const viewSuffix = view && view !== 'docs' ? `/${view}` : '';
+    window.location.hash = `${tab}/endpoint/${id}${viewSuffix}`;
+}
+/**
+ * Navigate to a section within a page (scroll to element)
+ * @param tab - Tab ID
+ * @param sectionId - Section/heading ID to scroll to
+ */ export function navigateToSection(tab, sectionId) {
+    window.location.hash = `${tab}/section/${sectionId}`;
+}
+/**
+ * Navigate to a tab (show default content for that tab)
+ * @param tab - Tab ID
+ */ export function navigateToTab(tab) {
+    window.location.hash = tab;
+}
+/**
+ * Switch view mode while keeping the current content
+ * @param view - View mode to switch to
+ */ export function switchView(view) {
+    const hash = window.location.hash.slice(1);
+    if (!hash) return;
+    // Remove existing view suffix if present
+    const cleanHash = hash.replace(/\/(playground|notes)$/, '');
+    // Add new view suffix (unless switching to docs, which is the default)
+    const viewSuffix = view !== 'docs' ? `/${view}` : '';
+    window.location.hash = `${cleanHash}${viewSuffix}`;
+}
+/**
+ * Clear current selection, optionally staying on a tab
+ * @param tab - Optional tab to stay on
+ */ export function clearSelection(tab) {
+    if (tab) {
+        window.location.hash = tab;
+    } else {
+        // Remove hash entirely using pushState to avoid scroll jump
+        window.history.pushState(null, '', window.location.pathname + window.location.search);
+    }
+}
+/**
+ * Update URL without triggering navigation (for history management)
+ * @param hash - Hash value (without #)
+ */ export function updateUrlSilently(hash) {
+    window.history.replaceState(null, '', `#${hash}`);
+}
+/**
+ * Push a new URL to history (for back/forward navigation)
+ * @param hash - Hash value (without #)
+ */ export function pushUrl(hash) {
+    window.history.pushState(null, '', `#${hash}`);
+}
+/**
+ * Build hash URL strings (for href attributes)
+ */ export const hashUrls = {
+    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}`
+};
+/**
+ * Parse a hash URL into its components
+ * @param hash - Hash value (with or without #)
+ * @returns Parsed components
+ */ export function parseHashUrl(hash) {
+    const cleanHash = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (!cleanHash) {
+        return {
+            tab: null,
+            type: null,
+            id: null,
+            view: 'docs'
+        };
+    }
+    const parts = cleanHash.split('/');
+    const tab = parts[0] || null;
+    const type = parts[1];
+    // 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;
+    // Validate type
+    const validTypes = [
+        'page',
+        'endpoint',
+        'section'
+    ];
+    const validatedType = type && validTypes.includes(type) ? type : null;
+    return {
+        tab,
+        type: validatedType,
+        id,
+        view
+    };
+}
+/**
+ * Check if two hash URLs point to the same content (ignoring view mode)
+ * @param hash1 - First hash
+ * @param hash2 - Second hash
+ * @returns True if they point to the same content
+ */ export function isSameContent(hash1, hash2) {
+    const parsed1 = parseHashUrl(hash1);
+    const parsed2 = parseHashUrl(hash2);
+    return parsed1.tab === parsed2.tab && parsed1.type === parsed2.type && parsed1.id === parsed2.id;
+}

package/renderer/package.json

@@ -33,6 +33,7 @@
     "dexie": "^4.0.10",
     "fflate": "^0.8.2",
     "graphql": "^16.12.0",
+    "graphql-language-service": "^5.5.0",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
     "mermaid": "^11.12.2",