deargui-vpl/docs/README.md

Documentation Index

Quick Start

• Quick Start Guide - Get up and running fast
• Debugging Guide - How to debug GUI and console variants

Console Variants

• Console Variants Guide - Full guide to console variants
• CMake Options - All configuration options
• Console Variant Setup - Implementation details

CLI/Headless Mode

• CLI Architecture ⭐ - Architectural options for true CLI mode
• CLI Implementation Example - Concrete implementation guide

Feature Guides

• Groups & Containers - Container system API
• Groups Architecture - Container system architecture
• Waypoints - Waypoint system
• Shortcuts - Keyboard shortcuts
• Screenshots - Taking screenshots
• MCP Screenshots - Using MCP for screenshots
• Plugins - Plugin system

Technical Documentation

• Classes Documentation - Class reference
• Complete Solution Summary - Full solution overview
• Implementation Summary - Implementation details
• TODO - Future enhancements

Test Reports

• Window State Test - Window state persistence tests
• Zoom to Content Fix - Zoom functionality fixes

Current State (Nov 2025)

Console Variants ✅

• GUI Variant: Standard Windows application with console attachment
• Console Variant: Always-visible console for debugging
• Visual Studio: Console variant is default startup project
• Build Scripts: Support for both variants

CLI Mode 🚧

• Status: Architecture documented, implementation ready
• Options: 5 architectural approaches analyzed
• Recommendation: Start with Option 1 (Headless Flag) for quick wins
• Next Step: Implement headless mode following cli-implementation-example.md

Architecture Summary

Current Architecture:
  blueprints-example.exe           (GUI with console attach)
  blueprints-example-console.exe   (GUI + always-visible console)

Proposed CLI Architecture:
  --headless flag → RunCLI()       (No UI, true CLI mode)
  (default)       → App.Run()      (Full UI as before)

Quick Reference

Build Commands

# GUI variant
./scripts/build.sh Debug

# Console variant
./scripts/build.sh Debug console

# Both
cmake --build build --config Debug

Run Commands

# GUI
./build/bin/blueprints-example_d.exe --file graph.json

# Console  
./build/bin/blueprints-example-console_d.exe --file graph.json

# CLI (once implemented)
./build/bin/blueprints-example-console_d.exe --headless --file graph.json --command validate

Visual Studio

# Open solution (console variant is default startup)
start build\imgui-node-editor.sln

# Press F5 to debug console variant

CMake Options

# Default: Both variants, console as startup
cmake -S examples -B build

# GUI only
cmake -S examples -B build -DBUILD_CONSOLE_VARIANTS=OFF

# Both, GUI as startup
cmake -S examples -B build -DUSE_CONSOLE_AS_STARTUP=OFF

Getting Started with CLI Mode

1. Read CLI Architecture to understand options
2. Follow CLI Implementation Example for step-by-step guide
3. Start with Option 1 (Headless Flag) - minimal changes, maximum benefit
4. Test with: --headless --file graph.json --command validate
5. Refactor to Option 3 or 4 later if needed

Key Decisions Made

Decision	Choice	Rationale
Console Variants	Build both by default	Better development experience
VS Startup Project	Console variant	Immediate console output for debugging
Entry Point	Shared entry_point.cpp	Reuse CLI parsing, single codebase
CLI Mode	Headless flag (recommended)	Quick to implement, validates use cases

Contributing

When adding new features:

• GUI features → Add to app.cpp / app-*.cpp
• CLI commands → Add to blueprints-cli.cpp (once created)
• Core logic → Extract to separate files for reuse
• Document in appropriate guide above