@brainfish-ai/devdoc 0.1.21 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainfish-ai/devdoc",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Documentation framework for developers. Write docs in MDX, preview locally, deploy to Brainfish.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/renderer/app/api/collections/route.ts

@@ -34,8 +34,8 @@ const BRAINFISH_API_BASE_URL = process.env.BRAINFISH_API_BASE_URL || 'https://ap
 const BRAINFISH_CATALOG_ID = process.env.BRAINFISH_CATALOG_ID || 'your_catalog_id_here'
 const BRAINFISH_JWT_TOKEN = process.env.BRAINFISH_JWT_TOKEN || 'your_jwt_token_here'
 
-// Debug logging
-if (process.env.NODE_ENV === 'development') {
+// Debug logging - only in verbose mode
+if (process.env.DEVDOC_VERBOSE === 'true') {
   console.log('[Collections] Config:', {
     useLocalSpec: USE_LOCAL_SPEC,
     starterPath: STARTER_PATH,
@@ -219,12 +219,10 @@ function loadGraphQLSchema(schemaPath: string): string | null {
       : resolvePath(relativePath)
     
     if (!existsSync(fullPath)) {
-      console.log('[Collections] GraphQL schema not found at:', fullPath)
       return null
     }
     
     const content = readFileSync(fullPath, 'utf-8')
-    console.log('[Collections] Loaded GraphQL schema from:', fullPath)
     return content
   } catch (error) {
     console.error('[Collections] Error loading GraphQL schema:', error)
@@ -243,14 +241,12 @@ function loadLocalSpec(specPath?: string): OpenApiSpec | null {
       : resolvePath(relativePath)
     
     if (!existsSync(fullPath)) {
-      console.log('[Collections] Local spec not found at:', fullPath)
       return null
     }
     
     const content = readFileSync(fullPath, 'utf-8')
     const spec = JSON.parse(content) as OpenApiSpec
     
-    console.log('[Collections] Loaded local spec:', spec.info?.title, 'v' + spec.info?.version, 'from', fullPath)
     return spec
   } catch (error) {
     console.error('[Collections] Error loading local spec:', error)
@@ -264,7 +260,6 @@ function loadDocsConfig(): DocsConfig | null {
     const configPath = resolvePath('docs.json')
     
     if (!existsSync(configPath)) {
-      console.log('[Collections] docs.json not found at:', configPath)
       return null
     }
     
@@ -282,7 +277,6 @@ function loadThemeConfig(): ThemeConfig | null {
     const configPath = resolvePath('theme.json')
     
     if (!existsSync(configPath)) {
-      console.log('[Collections] theme.json not found at:', configPath)
       return null
     }
     
@@ -577,8 +571,6 @@ async function fetchRemoteSpec(): Promise<OpenApiSpec | null> {
   try {
     const url = `${BRAINFISH_API_BASE_URL}/catalogs.openapi-spec`
     
-    console.log('[Collections] Fetching from:', url)
-    
     const response = await fetch(url, {
       method: 'POST',
       headers: {
@@ -612,7 +604,6 @@ async function fetchRemoteSpec(): Promise<OpenApiSpec | null> {
     
     const fallbackSpec = await CacheUtils.get<OpenApiSpec>(FALLBACK_CACHE_KEY)
     if (fallbackSpec) {
-      console.warn('[Collections] Using fallback cache')
       return fallbackSpec
     }
     
@@ -627,7 +618,6 @@ async function getOpenApiSpec(specPath?: string): Promise<OpenApiSpec | null> {
     if (localSpec) {
       return localSpec
     }
-    console.log('[Collections] Local spec not available, falling back to remote')
   }
   
   return fetchRemoteSpec()
@@ -811,11 +801,9 @@ async function getOrGenerateSummary(collection: BrainfishCollection, specVersion
   
   const cachedSummary = await CacheUtils.get<string>(versionedCacheKey)
   if (cachedSummary) {
-    console.log('[Collections] Using cached API summary for version:', specVersion)
     return cachedSummary
   }
   
-  console.log('[Collections] Generating new API summary for version:', specVersion)
   const summary = generateAPISummary(collection)
   const formattedSummary = formatAPISummaryForPrompt(summary)
   
@@ -869,8 +857,6 @@ export async function GET(request: Request) {
     // Get OpenAPI spec (with optional path for versioned specs)
     const spec = await getOpenApiSpec(specPath)
     
-    console.log('[Collections] Loaded', docGroups.length, 'doc groups,', navigationTabs.length, 'tabs,', changelogReleases.length, 'changelog releases,', apiVersions.length, 'API versions, selected:', selectedVersion)
-    
     // Handle no spec available
     if (!spec) {
       return NextResponse.json(

package/renderer/app/api/docs/route.ts

@@ -101,6 +101,11 @@ export async function GET(request: NextRequest) {
         title: frontmatter.title || slug,
         description: frontmatter.description,
         icon: frontmatter.icon,
+        // Page mode and layout options
+        mode: frontmatter.mode || 'default',
+        hideHeader: frontmatter.hideHeader || false,
+        fullWidth: frontmatter.fullWidth || false,
+        background: frontmatter.background,
       },
       mdxSource,
       rawContent: content, // Include raw content for changelog version extraction
@@ -171,6 +176,11 @@ async function handleMultiTenantDocs(projectSlug: string, slug: string): Promise
         title: frontmatter.title || slug,
         description: frontmatter.description,
         icon: frontmatter.icon,
+        // Page mode and layout options
+        mode: frontmatter.mode || 'default',
+        hideHeader: frontmatter.hideHeader || false,
+        fullWidth: frontmatter.fullWidth || false,
+        background: frontmatter.background,
       },
       mdxSource,
       rawContent: content,

package/renderer/app/api/schema/route.ts

@@ -1,15 +1,23 @@
 import { NextRequest, NextResponse } from 'next/server'
 import { readFileSync, existsSync } from 'fs'
-import { join } from 'path'
+import { join, isAbsolute } from 'path'
 import { getProjectContent } from '@/lib/storage/blob'
 
-// Get the docs directory
+// Configuration - match collections route
+const STARTER_PATH = process.env.STARTER_PATH || 'devdoc-docs'
+
+// Get the docs directory - respects STARTER_PATH for local development
 function getDocsDir(): string {
   const projectSlug = process.env.BRAINFISH_PROJECT_SLUG
   if (projectSlug) {
     return join(process.cwd(), '.devdoc', projectSlug)
   }
-  return join(process.cwd(), 'devdoc-docs')
+  
+  // Use STARTER_PATH (can be absolute or relative)
+  if (isAbsolute(STARTER_PATH)) {
+    return STARTER_PATH
+  }
+  return join(process.cwd(), STARTER_PATH)
 }
 
 export async function GET(request: NextRequest) {

package/renderer/app/globals.css

@@ -1100,4 +1100,92 @@ code[data-line-numbers] > [data-line]::before {
 /* Scroll margin for agent navigation */
 [id] {
   scroll-margin-top: 80px;
+}
+
+/* ============================================
+   Custom Mode Page Styles (Landing Pages)
+   ============================================ */
+
+/* Custom mode pages should fill the entire content area */
+.docs-page-custom {
+  width: 100%;
+  min-height: 100%;
+  margin: 0;
+  padding: 0;
+}
+
+/* Ensure custom content children stretch to fill width */
+.docs-custom-content {
+  width: 100%;
+  margin: 0;
+  padding: 0;
+}
+
+/* All direct children of custom content should be full width */
+.docs-custom-content > * {
+  width: 100%;
+  margin-left: 0;
+  margin-right: 0;
+}
+
+/* Landing page components should not have prose constraints */
+.docs-custom-content .landing-hero,
+.docs-custom-content .landing-section {
+  max-width: none;
+  width: 100%;
+  margin-left: 0;
+  margin-right: 0;
+}
+
+/* When viewing a custom mode page, the content area should have no background */
+.docs-content-area:has(.docs-page-custom) {
+  background: transparent !important;
+  padding: 0 !important;
+}
+
+/* Ensure the main header doesn't shrink */
+.docs-main-header {
+  flex-shrink: 0 !important;
+  width: 100% !important;
+}
+
+/* Ensure docs-main container maintains width and doesn't collapse */
+.docs-main {
+  flex: 1 1 0% !important;
+  min-width: 0 !important;
+  width: 100% !important;
+}
+
+/* Ensure docs-layout children don't cause layout shifts */
+.docs-layout {
+  display: flex !important;
+}
+
+.docs-layout > .docs-sidebar {
+  flex-shrink: 0 !important;
+}
+
+/* Prevent content area from affecting parent layout */
+.docs-content-area {
+  flex: 1 1 auto !important;
+  min-height: 0 !important;
+}
+
+/* Remove any default margins from sections in custom pages */
+.docs-custom-content section {
+  margin: 0;
+}
+
+/* Ensure Hero sections fill entire width */
+.landing-hero {
+  width: 100%;
+  margin: 0;
+  padding-left: 0;
+  padding-right: 0;
+}
+
+/* Section components fill entire width */
+.landing-section {
+  width: 100%;
+  margin: 0;
 }

package/renderer/components/docs/mdx/index.ts

@@ -100,6 +100,23 @@ export {
   UpdateItem,
 } from './changelog'
 
+// Landing Page Components
+export {
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
+} from './landing'
+
 // Re-export types
 export type { Frontmatter } from '@/lib/docs/mdx/frontmatter'
 
@@ -123,6 +140,7 @@ import { Badge } from './badge'
 import { Mermaid } from './mermaid'
 import { PDF, Audio, Download } from './file-embeds'
 import { ChangelogEntry, ChangelogTitle, ChangelogDescription, ChangelogImage, BreakingChange, MoreUpdates, UpdateItem } from './changelog'
+import { Hero, Pre, Tagline, Headline, Description, CommandBox, Section, Center, FeatureGrid, FeatureItem, ButtonLink, Spacer, Divider } from './landing'
 
 export const mdxComponents = {
   // Callouts
@@ -199,6 +217,21 @@ export const mdxComponents = {
   BreakingChange,
   MoreUpdates,
   UpdateItem,
+  
+  // Landing Page
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
 }
 
 export default mdxComponents

package/renderer/components/docs/mdx/landing.tsx

@@ -0,0 +1,684 @@
+'use client'
+
+import React, { useState } from 'react'
+import { cn } from '@/lib/utils'
+import { 
+  Copy, 
+  Check, 
+  ArrowRight, 
+  GithubLogo, 
+  Terminal,
+  ArrowUpRight,
+  RocketLaunch,
+} from '@phosphor-icons/react'
+import { getPhosphorIcon, type PhosphorIconComponent } from '@/lib/utils/icons'
+
+// Direct icon map for commonly used icons (fallback if dynamic import fails)
+const iconMap: Record<string, PhosphorIconComponent> = {
+  'arrow-right': ArrowRight,
+  'github-logo': GithubLogo,
+  'terminal': Terminal,
+  'arrow-up-right': ArrowUpRight,
+  'rocket-launch': RocketLaunch,
+}
+
+/**
+ * Landing Page Components for MDX Documentation
+ * 
+ * These components enable creating custom landing pages similar to skills.sh
+ * with hero sections, command boxes, feature grids, and more.
+ */
+
+/**
+ * Hero Section Component
+ * 
+ * A full-width hero section for landing pages with optional
+ * logo/ASCII art, tagline, and description.
+ */
+interface HeroProps {
+  children?: React.ReactNode
+  className?: string
+  /** Background variant */
+  variant?: 'default' | 'gradient' | 'dark' | 'light' | 'pattern'
+  /** Vertical alignment */
+  align?: 'top' | 'center' | 'bottom'
+  /** Minimum height */
+  minHeight?: 'sm' | 'md' | 'lg' | 'full'
+}
+
+export function Hero({ 
+  children, 
+  className,
+  variant = 'default',
+  align = 'center',
+  minHeight = 'md'
+}: HeroProps) {
+  const variantStyles = {
+    default: 'bg-background text-foreground',
+    gradient: 'bg-gradient-to-b from-background via-background to-muted/30 text-foreground',
+    dark: 'bg-zinc-950 text-white [&_.landing-tagline]:text-zinc-400 [&_.landing-headline]:text-white [&_.landing-description]:text-zinc-300 [&_.landing-button]:border-zinc-600',
+    light: 'bg-white text-zinc-900 [&_.landing-tagline]:text-zinc-500 [&_.landing-headline]:text-zinc-900 [&_.landing-description]:text-zinc-600 [&_.landing-button]:border-zinc-300',
+    pattern: 'bg-background bg-[radial-gradient(ellipse_at_top,_var(--tw-gradient-stops))] from-primary/10 via-background to-background text-foreground',
+  }
+  
+  const alignStyles = {
+    top: 'items-start pt-12',
+    center: 'items-center',
+    bottom: 'items-end pb-12',
+  }
+  
+  const heightStyles = {
+    sm: 'min-h-[40vh]',
+    md: 'min-h-[60vh]',
+    lg: 'min-h-[80vh]',
+    full: 'min-h-screen',
+  }
+  
+  return (
+    <section 
+      className={cn(
+        'landing-hero w-full flex flex-col justify-center',
+        variantStyles[variant],
+        alignStyles[align],
+        heightStyles[minHeight],
+        className
+      )}
+    >
+      <div className="landing-hero-content w-full max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 text-center">
+        {children}
+      </div>
+    </section>
+  )
+}
+
+/**
+ * Pre Component
+ * 
+ * Pre-formatted text component for ASCII art, logos, and other
+ * monospace content that needs to preserve whitespace.
+ */
+interface PreProps {
+  children: React.ReactNode
+  className?: string
+  /** Font size preset */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  /** Text alignment */
+  align?: 'left' | 'center' | 'right'
+  /** Text color variant */
+  color?: 'default' | 'muted' | 'primary' | 'white'
+  /** Line height */
+  leading?: 'none' | 'tight' | 'normal' | 'relaxed'
+  /** Hide from screen readers (decorative content) */
+  decorative?: boolean
+}
+
+export function Pre({ 
+  children, 
+  className,
+  size = 'md',
+  align = 'center',
+  color = 'default',
+  leading = 'tight',
+  decorative = false,
+}: PreProps) {
+  const sizeStyles = {
+    xs: 'text-[0.5rem] sm:text-xs',
+    sm: 'text-xs sm:text-sm',
+    md: 'text-sm sm:text-base md:text-lg',
+    lg: 'text-base sm:text-lg md:text-xl lg:text-2xl',
+    xl: 'text-lg sm:text-xl md:text-2xl lg:text-3xl xl:text-4xl',
+  }
+  
+  const alignStyles = {
+    left: 'text-left',
+    center: 'text-center mx-auto',
+    right: 'text-right ml-auto',
+  }
+  
+  const colorStyles = {
+    default: 'text-foreground',
+    muted: 'text-muted-foreground',
+    primary: 'text-primary',
+    white: 'text-white',
+  }
+  
+  const leadingStyles = {
+    none: 'leading-none',
+    tight: 'leading-tight',
+    normal: 'leading-normal',
+    relaxed: 'leading-relaxed',
+  }
+  
+  return (
+    <pre 
+      className={cn(
+        'landing-pre font-mono whitespace-pre select-none overflow-x-auto',
+        sizeStyles[size],
+        alignStyles[align],
+        colorStyles[color],
+        leadingStyles[leading],
+        className
+      )}
+      aria-hidden={decorative}
+    >
+      {children}
+    </pre>
+  )
+}
+
+/**
+ * Tagline Component
+ * 
+ * Displays a prominent tagline or subtitle.
+ */
+interface TaglineProps {
+  children: React.ReactNode
+  className?: string
+  /** Visual style */
+  variant?: 'default' | 'muted' | 'accent'
+  /** Letter spacing */
+  tracking?: 'normal' | 'wide' | 'wider' | 'widest'
+}
+
+export function Tagline({ 
+  children, 
+  className,
+  variant = 'default',
+  tracking = 'wider'
+}: TaglineProps) {
+  const variantStyles = {
+    default: '', // Inherit from parent
+    muted: 'opacity-60',
+    accent: 'text-primary',
+  }
+  
+  const trackingStyles = {
+    normal: 'tracking-normal',
+    wide: 'tracking-wide',
+    wider: 'tracking-wider',
+    widest: 'tracking-widest',
+  }
+  
+  // Use div instead of p to avoid hydration errors when MDX wraps content in <p>
+  return (
+    <div 
+      className={cn(
+        'landing-tagline text-sm sm:text-base font-medium uppercase',
+        variantStyles[variant],
+        trackingStyles[tracking],
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Headline Component
+ * 
+ * Large display text for hero headlines.
+ */
+interface HeadlineProps {
+  children: React.ReactNode
+  className?: string
+  /** Size preset */
+  size?: 'md' | 'lg' | 'xl' | '2xl'
+  /** Font weight */
+  weight?: 'normal' | 'medium' | 'semibold' | 'bold'
+}
+
+export function Headline({ 
+  children, 
+  className,
+  size = 'xl',
+  weight = 'normal'
+}: HeadlineProps) {
+  const sizeStyles = {
+    md: 'text-xl sm:text-2xl md:text-3xl',
+    lg: 'text-2xl sm:text-3xl md:text-4xl',
+    xl: 'text-3xl sm:text-4xl md:text-5xl',
+    '2xl': 'text-4xl sm:text-5xl md:text-6xl',
+  }
+  
+  const weightStyles = {
+    normal: 'font-normal',
+    medium: 'font-medium',
+    semibold: 'font-semibold',
+    bold: 'font-bold',
+  }
+  
+  return (
+    <h1 
+      className={cn(
+        'landing-headline leading-tight',
+        sizeStyles[size],
+        weightStyles[weight],
+        className
+      )}
+    >
+      {children}
+    </h1>
+  )
+}
+
+/**
+ * Description Component
+ * 
+ * Body text for hero descriptions.
+ */
+interface DescriptionProps {
+  children: React.ReactNode
+  className?: string
+  /** Size preset */
+  size?: 'sm' | 'md' | 'lg'
+  /** Max width */
+  maxWidth?: 'sm' | 'md' | 'lg' | 'full'
+}
+
+export function Description({ 
+  children, 
+  className,
+  size = 'lg',
+  maxWidth = 'lg'
+}: DescriptionProps) {
+  const sizeStyles = {
+    sm: 'text-sm sm:text-base',
+    md: 'text-base sm:text-lg',
+    lg: 'text-lg sm:text-xl',
+  }
+  
+  const maxWidthStyles = {
+    sm: 'max-w-md',
+    md: 'max-w-xl',
+    lg: 'max-w-2xl',
+    full: 'max-w-full',
+  }
+  
+  // Use div instead of p to avoid hydration errors when MDX wraps content in <p>
+  return (
+    <div 
+      className={cn(
+        'landing-description opacity-80 mx-auto',
+        sizeStyles[size],
+        maxWidthStyles[maxWidth],
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Command Box Component
+ * 
+ * A copyable command display with a dark background,
+ * similar to the skills.sh installation command box.
+ */
+interface CommandBoxProps {
+  /** The command to display */
+  command: string
+  /** Optional prefix like $ or > */
+  prefix?: string
+  className?: string
+  /** Visual variant - 'default' is dark (terminal style), 'light' adapts to theme */
+  variant?: 'default' | 'minimal' | 'bordered' | 'light'
+}
+
+export function CommandBox({ 
+  command, 
+  prefix = '$',
+  className,
+  variant = 'default'
+}: CommandBoxProps) {
+  const [copied, setCopied] = useState(false)
+  
+  const handleCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(command)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch (err) {
+      console.error('Failed to copy:', err)
+    }
+  }
+  
+  const variantStyles = {
+    default: 'bg-zinc-950 border border-zinc-800 shadow-lg',
+    minimal: 'bg-zinc-900',
+    bordered: 'bg-zinc-950 border-2 border-zinc-700',
+    light: 'bg-muted border border-border shadow-sm',
+  }
+  
+  const textStyles = {
+    default: 'text-white',
+    minimal: 'text-white',
+    bordered: 'text-white',
+    light: 'text-foreground',
+  }
+  
+  const prefixStyles = {
+    default: 'text-zinc-400',
+    minimal: 'text-zinc-400',
+    bordered: 'text-zinc-400',
+    light: 'text-muted-foreground',
+  }
+  
+  const buttonStyles = {
+    default: 'text-zinc-300 hover:text-white hover:bg-zinc-700',
+    minimal: 'text-zinc-300 hover:text-white hover:bg-zinc-700',
+    bordered: 'text-zinc-300 hover:text-white hover:bg-zinc-700',
+    light: 'text-muted-foreground hover:text-foreground hover:bg-muted-foreground/10',
+  }
+  
+  return (
+    <div 
+      className={cn(
+        'landing-command-box inline-flex items-center gap-3 rounded-lg px-4 py-3',
+        variantStyles[variant],
+        className
+      )}
+    >
+      <code className={cn('flex items-center gap-2 font-mono text-sm sm:text-base', textStyles[variant])}>
+        {prefix && (
+          <span className={cn('select-none', prefixStyles[variant])}>{prefix}</span>
+        )}
+        <span>{command}</span>
+      </code>
+      <button
+        type="button"
+        onClick={handleCopy}
+        className={cn(
+          'p-1.5 rounded transition-colors',
+          'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
+          buttonStyles[variant]
+        )}
+        title="Copy command"
+      >
+        {copied ? (
+          <Check className="h-4 w-4 text-emerald-500" weight="bold" />
+        ) : (
+          <Copy className="h-4 w-4" />
+        )}
+      </button>
+    </div>
+  )
+}
+
+/**
+ * Section Component
+ * 
+ * A full-width section wrapper for landing page content.
+ */
+interface SectionProps {
+  children: React.ReactNode
+  className?: string
+  /** Section ID for anchor links */
+  id?: string
+  /** Background variant */
+  variant?: 'default' | 'muted' | 'dark' | 'light' | 'accent'
+  /** Padding preset */
+  padding?: 'none' | 'sm' | 'md' | 'lg' | 'xl'
+}
+
+export function Section({ 
+  children, 
+  className,
+  id,
+  variant = 'default',
+  padding = 'lg'
+}: SectionProps) {
+  const variantStyles = {
+    default: 'bg-background text-foreground',
+    muted: 'bg-muted/30 text-foreground',
+    dark: 'bg-zinc-950 text-white [&_.landing-tagline]:text-zinc-400 [&_.landing-headline]:text-white [&_.landing-description]:text-zinc-300 [&_.landing-feature-title]:text-white [&_.landing-feature-description]:text-zinc-400 [&_.landing-button]:border-zinc-600',
+    light: 'bg-white text-zinc-900 [&_.landing-tagline]:text-zinc-500 [&_.landing-headline]:text-zinc-900 [&_.landing-description]:text-zinc-600 [&_.landing-feature-title]:text-zinc-900 [&_.landing-feature-description]:text-zinc-600 [&_.landing-button]:border-zinc-300',
+    accent: 'bg-primary/5 text-foreground',
+  }
+  
+  const paddingStyles = {
+    none: '',
+    sm: 'py-8 sm:py-12',
+    md: 'py-12 sm:py-16',
+    lg: 'py-16 sm:py-24',
+    xl: 'py-24 sm:py-32',
+  }
+  
+  return (
+    <section 
+      id={id}
+      className={cn(
+        'landing-section w-full',
+        variantStyles[variant],
+        paddingStyles[padding],
+        className
+      )}
+    >
+      <div className="landing-section-content max-w-5xl mx-auto px-4 sm:px-6 lg:px-8">
+        {children}
+      </div>
+    </section>
+  )
+}
+
+/**
+ * Center Component
+ * 
+ * Centers content horizontally and optionally vertically.
+ */
+interface CenterProps {
+  children: React.ReactNode
+  className?: string
+  /** Stack children with gap */
+  gap?: 'none' | 'sm' | 'md' | 'lg'
+}
+
+export function Center({ children, className, gap = 'md' }: CenterProps) {
+  const gapStyles = {
+    none: '',
+    sm: 'space-y-2',
+    md: 'space-y-4',
+    lg: 'space-y-8',
+  }
+  
+  return (
+    <div 
+      className={cn(
+        'landing-center flex flex-col items-center text-center',
+        gapStyles[gap],
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Feature Grid Component
+ * 
+ * A responsive grid for displaying feature cards.
+ */
+interface FeatureGridProps {
+  children: React.ReactNode
+  className?: string
+  /** Number of columns */
+  cols?: 2 | 3 | 4
+}
+
+export function FeatureGrid({ children, className, cols = 3 }: FeatureGridProps) {
+  const colStyles = {
+    2: 'grid-cols-1 md:grid-cols-2',
+    3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+    4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+  }
+  
+  return (
+    <div 
+      className={cn(
+        'landing-feature-grid grid gap-6',
+        colStyles[cols],
+        className
+      )}
+    >
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Feature Item Component
+ * 
+ * Individual feature card with icon, title, and description.
+ */
+interface FeatureItemProps {
+  children?: React.ReactNode
+  title?: string
+  icon?: React.ReactNode
+  className?: string
+}
+
+export function FeatureItem({ children, title, icon, className }: FeatureItemProps) {
+  return (
+    <div 
+      className={cn(
+        'landing-feature-item p-6 rounded-xl border border-border/50 bg-card/50',
+        'hover:border-primary/30 hover:bg-card/80 transition-colors',
+        className
+      )}
+    >
+      {icon && (
+        <div className="landing-feature-icon mb-4 text-primary text-2xl">
+          {icon}
+        </div>
+      )}
+      {title && (
+        <h3 className="landing-feature-title text-lg font-semibold mb-2">
+          {title}
+        </h3>
+      )}
+      {children && (
+        <div className="landing-feature-description text-sm opacity-80">
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Button Link Component
+ * 
+ * Styled button links for CTAs.
+ */
+interface ButtonLinkProps {
+  href: string
+  children: React.ReactNode
+  className?: string
+  /** Visual variant */
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost'
+  /** Size preset */
+  size?: 'sm' | 'md' | 'lg'
+  /** Phosphor icon name (e.g., "arrow-right", "github-logo") */
+  icon?: string
+  /** Icon position */
+  iconPosition?: 'left' | 'right'
+}
+
+
+export function ButtonLink({ 
+  href, 
+  children, 
+  className,
+  variant = 'primary',
+  size = 'md',
+  icon,
+  iconPosition = 'right'
+}: ButtonLinkProps) {
+  const variantStyles = {
+    primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+    secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+    outline: 'border border-current/30 bg-transparent text-current hover:bg-current/10',
+    ghost: 'bg-transparent text-current hover:bg-current/10',
+  }
+  
+  const sizeStyles = {
+    sm: 'px-3 py-1.5 text-sm',
+    md: 'px-4 py-2 text-base',
+    lg: 'px-6 py-3 text-lg',
+  }
+  
+  const iconSizes = {
+    sm: 'h-4 w-4',
+    md: 'h-5 w-5',
+    lg: 'h-5 w-5',
+  }
+  
+  // Try direct map first, then dynamic lookup
+  const IconComponent = icon ? (iconMap[icon] || getPhosphorIcon(icon)) : null
+  
+  return (
+    <a 
+      href={href}
+      className={cn(
+        'landing-button inline-flex items-center justify-center gap-2 rounded-lg font-medium',
+        'transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50',
+        variantStyles[variant],
+        sizeStyles[size],
+        className
+      )}
+    >
+      {IconComponent && iconPosition === 'left' && (
+        <IconComponent className={iconSizes[size]} weight="bold" />
+      )}
+      {children}
+      {IconComponent && iconPosition === 'right' && (
+        <IconComponent className={iconSizes[size]} weight="bold" />
+      )}
+    </a>
+  )
+}
+
+/**
+ * Spacer Component
+ * 
+ * Adds vertical spacing.
+ */
+interface SpacerProps {
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+  className?: string
+}
+
+export function Spacer({ size = 'md', className }: SpacerProps) {
+  const sizeStyles = {
+    xs: 'h-2',
+    sm: 'h-4',
+    md: 'h-8',
+    lg: 'h-12',
+    xl: 'h-16',
+    '2xl': 'h-24',
+  }
+  
+  return <div className={cn('landing-spacer', sizeStyles[size], className)} />
+}
+
+/**
+ * Divider Component
+ * 
+ * Horizontal divider line.
+ */
+interface DividerProps {
+  className?: string
+  variant?: 'solid' | 'dashed' | 'gradient'
+}
+
+export function Divider({ className, variant = 'solid' }: DividerProps) {
+  const variantStyles = {
+    solid: 'border-t border-border',
+    dashed: 'border-t border-dashed border-border',
+    gradient: 'h-px bg-gradient-to-r from-transparent via-border to-transparent border-none',
+  }
+  
+  return <hr className={cn('landing-divider w-full my-8', variantStyles[variant], className)} />
+}

package/renderer/components/docs-viewer/content/doc-page.tsx

@@ -120,6 +120,20 @@ import {
   PDF,
   Audio,
   Download,
+  // Landing Page Components
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
 } from '../../docs/mdx/index'
 
 // MDX components mapping
@@ -190,6 +204,21 @@ const mdxComponents = {
   Audio,
   Download,
   
+  // Landing Page
+  Hero,
+  Pre,
+  Tagline,
+  Headline,
+  Description,
+  CommandBox,
+  Section,
+  Center,
+  FeatureGrid,
+  FeatureItem,
+  ButtonLink,
+  Spacer,
+  Divider,
+  
   // Links
   a: MdxLink,
 }
@@ -204,6 +233,11 @@ interface DocPageData {
     title: string
     description?: string
     icon?: string
+    // Page mode and layout options
+    mode?: 'default' | 'wide' | 'custom'
+    hideHeader?: boolean
+    fullWidth?: boolean
+    background?: string
   }
   mdxSource: MDXRemoteSerializeResult
 }
@@ -244,7 +278,7 @@ export function DocPage({ slug }: DocPageProps) {
   
   if (loading) {
     return (
-      <div className="docs-page docs-page-loading max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
+      <div className="docs-page docs-page-loading w-full min-h-[200px]">
         <div className="docs-loading flex items-center justify-center py-12">
           <Spinner className="h-6 w-6 animate-spin text-muted-foreground" />
         </div>
@@ -254,7 +288,7 @@ export function DocPage({ slug }: DocPageProps) {
   
   if (error || !pageData) {
     return (
-      <div className="docs-page docs-page-error max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
+      <div className="docs-page docs-page-error w-full min-h-[200px]">
         <div className="docs-error text-center py-12">
           <p className="text-destructive">{error || 'Page not found'}</p>
         </div>
@@ -262,19 +296,52 @@ export function DocPage({ slug }: DocPageProps) {
     )
   }
   
-  return (
-    <div ref={contentRef} className="docs-page docs-content max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8">
-      {/* Page header */}
-      <div className="docs-page-header mb-6">
-        <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground">
-          {pageData.frontmatter.title}
-        </h1>
-        {pageData.frontmatter.description && (
-          <p className="docs-content-description text-lg text-muted-foreground">
-            {pageData.frontmatter.description}
-          </p>
-        )}
+  const { mode = 'default', hideHeader, fullWidth, background } = pageData.frontmatter
+  const isCustomMode = mode === 'custom'
+  const isWideMode = mode === 'wide'
+  const showHeader = !hideHeader && !isCustomMode
+  
+  // Custom mode: Full-width layout for landing pages
+  if (isCustomMode) {
+    return (
+      <div 
+        ref={contentRef} 
+        className="docs-page docs-page-custom docs-content w-full min-h-full"
+        style={{ 
+          background: background || 'var(--background)',
+          // Ensure the content fills the entire viewport width within the content area
+          marginLeft: 0,
+          marginRight: 0,
+        }}
+      >
+        {/* Custom pages render MDX content directly without container constraints */}
+        <div className="docs-custom-content [&>*]:w-full">
+          <MDXRemote {...pageData.mdxSource} components={mdxComponents} />
+        </div>
       </div>
+    )
+  }
+  
+  // Default/Wide mode: Standard documentation layout
+  const containerClass = isWideMode 
+    ? 'max-w-6xl' // Wide mode
+    : 'max-w-4xl' // Default mode
+  
+  return (
+    <div ref={contentRef} className={`docs-page docs-content ${containerClass} mx-auto px-4 py-6 sm:px-8 sm:py-8`}>
+      {/* Page header - shown unless hideHeader is true */}
+      {showHeader && (
+        <div className="docs-page-header mb-6">
+          <h1 className="docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground">
+            {pageData.frontmatter.title}
+          </h1>
+          {pageData.frontmatter.description && (
+            <p className="docs-content-description text-lg text-muted-foreground">
+              {pageData.frontmatter.description}
+            </p>
+          )}
+        </div>
+      )}
       
       {/* Page content - MDX rendered with custom components */}
       <div className="docs-prose prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-muted-foreground prose-strong:text-foreground prose-code:text-foreground prose-pre:bg-muted prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-pre:overflow-x-auto prose-table:w-full prose-th:text-left prose-th:p-3 prose-th:bg-muted prose-td:p-3 prose-td:border-b prose-td:border-border">

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

@@ -1285,7 +1285,7 @@ function DocsWithMode({
   }, [collection?.defaultTheme, setTheme])
   
   return (
-    <>
+    <div className="docs-viewer-root flex flex-col h-screen overflow-hidden">
       {/* Notice */}
       {collection.notice && (
         <Notice config={collection.notice} storageKey="docs-notice" />
@@ -1313,7 +1313,7 @@ function DocsWithMode({
         docsNavbar={collection.docsNavbar}
       />
       
-      <div className="docs-layout flex h-[calc(100vh-6rem)] overflow-hidden relative z-0">
+      <div className="docs-layout flex flex-1 overflow-hidden relative z-0 min-h-0">
         {/* Left Sidebar - Hidden for changelog */}
         {!showChangelog && (
           <DocsSidebar
@@ -1344,9 +1344,9 @@ function DocsWithMode({
         )}
         
         {/* Center - Toggles between API Client/Playground and Notes */}
-        <div className="docs-main flex-1 flex flex-col overflow-hidden min-w-0">
+        <div className="docs-main flex-1 flex flex-col overflow-hidden" style={{ minWidth: 0, flexBasis: 0, flexGrow: 1 }}>
           {/* Mode Toggle Header */}
-          <div className="docs-main-header flex items-center justify-end px-3 sm:px-4 h-[41px] border-b border-border bg-muted/30">
+          <div className="docs-main-header flex items-center justify-end px-3 sm:px-4 h-[41px] border-b border-border bg-muted/30 flex-shrink-0">
             <ModeToggleTabs hasEndpoint={!!selectedRequest} />
           </div>
           
@@ -1446,7 +1446,7 @@ function DocsWithMode({
         open={showAuthModal} 
         onClose={() => setShowAuthModal(false)} 
       />
-    </>
+    </div>
   )
 }
 

package/renderer/components/docs-viewer/sidebar/sidebar-item.tsx

@@ -2,21 +2,7 @@
 
 import { ReactNode, useRef, useEffect, useLayoutEffect, useState, createContext, useContext } from 'react'
 import { cn } from '@/lib/utils'
-import * as PhosphorIcons from '@phosphor-icons/react'
-
-// Helper to get Phosphor icon component from name
-function getIcon(iconName?: string): React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | null {
-  if (!iconName) return null
-  
-  // Convert kebab-case to PascalCase for Phosphor icons
-  const pascalCase = iconName
-    .split('-')
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join('')
-  
-  const IconComponent = (PhosphorIcons as Record<string, unknown>)[pascalCase] as React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | undefined
-  return IconComponent || null
-}
+import { getPhosphorIcon } from '@/lib/utils/icons'
 
 // Context for the sliding indicator
 interface SlidingIndicatorContextType {
@@ -152,7 +138,7 @@ export function SidebarItem({
   const buttonRef = useRef<HTMLButtonElement>(null)
   const context = useContext(SlidingIndicatorContext)
   const id = itemId || String(children)
-  const IconComponent = getIcon(icon)
+  const IconComponent = getPhosphorIcon(icon)
 
   // Register this item with the sliding indicator provider
   useEffect(() => {

package/renderer/components/docs-viewer/sidebar/sidebar-section.tsx

@@ -2,7 +2,7 @@
 
 import { ReactNode } from 'react'
 import { cn } from '@/lib/utils'
-import * as PhosphorIcons from '@phosphor-icons/react'
+import { getPhosphorIcon } from '@/lib/utils/icons'
 
 interface SidebarSectionProps {
   title: string
@@ -12,25 +12,11 @@ interface SidebarSectionProps {
   icon?: string
 }
 
-// Map of common icon names to Phosphor components
-function getIcon(iconName?: string): React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | null {
-  if (!iconName) return null
-  
-  // Convert kebab-case to PascalCase for Phosphor icons
-  const pascalCase = iconName
-    .split('-')
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join('')
-  
-  const IconComponent = (PhosphorIcons as Record<string, unknown>)[pascalCase] as React.ComponentType<{ className?: string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }> | undefined
-  return IconComponent || null
-}
-
 /**
  * Sidebar Section component - groups items under a title with optional icon
  */
 export function SidebarSection({ title, children, className = '', icon }: SidebarSectionProps) {
-  const IconComponent = getIcon(icon)
+  const IconComponent = getPhosphorIcon(icon)
   
   return (
     <div className={cn('docs-sidebar-section flex flex-col', className)}>

package/renderer/lib/docs/mdx/frontmatter.ts

@@ -17,8 +17,19 @@ export const frontmatterSchema = z.object({
   icon: z.string().optional(),
   
   // Page behavior
+  // - 'default': Standard documentation page with max-width container
+  // - 'wide': Wide container for content that needs more space
+  // - 'custom': Full-width custom layout (no container, no header) - for landing pages
   mode: z.enum(['default', 'wide', 'custom']).optional(),
   
+  // Custom page options (only used when mode: 'custom')
+  // Hides the default page header (title & description)
+  hideHeader: z.boolean().optional(),
+  // Full-width layout without container constraints
+  fullWidth: z.boolean().optional(),
+  // Custom background color or gradient
+  background: z.string().optional(),
+  
   // OpenAPI integration
   openapi: z.string().optional(),
   api: z.string().optional(),

package/renderer/lib/utils/icons.ts

@@ -0,0 +1,48 @@
+import * as PhosphorIcons from '@phosphor-icons/react'
+
+export type PhosphorIconWeight = 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone'
+
+export type PhosphorIconComponent = React.ComponentType<{
+  className?: string
+  weight?: PhosphorIconWeight
+}>
+
+/**
+ * Get a Phosphor icon component by its kebab-case name
+ * 
+ * @param iconName - The icon name in kebab-case (e.g., "arrow-right", "github-logo")
+ * @returns The Phosphor icon component or null if not found
+ * 
+ * @example
+ * const Icon = getPhosphorIcon('arrow-right')
+ * if (Icon) {
+ *   return <Icon className="h-5 w-5" weight="bold" />
+ * }
+ */
+export function getPhosphorIcon(iconName?: string): PhosphorIconComponent | null {
+  if (!iconName) return null
+  
+  // Convert kebab-case to PascalCase for Phosphor icons
+  const pascalCase = iconName
+    .split('-')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+  
+  const IconComponent = (PhosphorIcons as Record<string, unknown>)[pascalCase]
+  
+  if (typeof IconComponent === 'function') {
+    return IconComponent as PhosphorIconComponent
+  }
+  
+  return null
+}
+
+/**
+ * Check if a Phosphor icon exists by name
+ * 
+ * @param iconName - The icon name in kebab-case
+ * @returns true if the icon exists
+ */
+export function hasPhosphorIcon(iconName?: string): boolean {
+  return getPhosphorIcon(iconName) !== null
+}