📚 WINGMAN CEF INTEGRATION - COMPLETE INDEX

Last Updated: 2025-10-13
Status: ✅ GPU-ENABLED CEF WORKING

🚀 QUICK START (NEW USERS)

Want to build and test right now?

cd C:\wingman
COMPLETE_FIX_AND_TEST.bat

That's it! This single script does everything:

Clears logs
Rebuilds plugin
Installs to VST3 folder
Verifies all files
Gives you testing instructions

📖 DOCUMENTATION GUIDE

🆘 I NEED HELP RIGHT NOW!

Problem	Solution
Black screen	Read: `CEF_GPU_FIX_SOLUTION.md`
White screen	Run: `diagnose_cef.bat`
JUCE sliders	Check: `CEF_GUARDRAILS.md` Rule #2
DAW crashes	Read: `CEF_GUARDRAILS.md` Rule #4
Build errors	Run: `COMPLETE_FIX_AND_TEST.bat`

🎓 I WANT TO UNDERSTAND EVERYTHING

Read in this order:

CEF_GPU_FIX_SOLUTION.md (5 min)
- What was wrong
- What was fixed
- How to test
CEF_GUARDRAILS.md (15 min)
- 10 critical rules
- Common mistakes
- How to avoid breaking CEF
COMPLETE_GUIDE.md (30 min)
- Deep technical details
- Advanced configuration
- Troubleshooting matrix

🤖 I'M AN AI ASSISTANT HELPING WITH THIS PROJECT

READ THIS FIRST: CEF_GUARDRAILS.md

CRITICAL RULES:

✅ Enable GPU (don't disable) if user wants fancy UI
✅ Return WingmanEditor, not GenericAudioProcessorEditor
✅ Use native window mode (not OSR)
✅ Single process mode always
✅ Create browser after window exists

BEFORE ANY CHANGES:

Read all 10 rules in CEF_GUARDRAILS.md
Check existing code first
Test in real DAW after changes
Run diagnose_after_test.bat to verify

🔧 SCRIPTS REFERENCE

Build & Install Scripts

COMPLETE_FIX_AND_TEST.bat ⭐ RECOMMENDED

Does everything: clean, build, install, verify
Use this for first-time setup or after major changes
Shows detailed progress and testing instructions

rebuild_and_install.bat

Quick rebuild and install
Use for minor code changes
Faster than complete fix

Diagnostic Scripts

diagnose_cef.bat

Run BEFORE testing
Checks if all files are present
Verifies plugin structure
Opens detailed report

diagnose_after_test.bat

Run AFTER testing in DAW
Analyzes CEF logs
Identifies specific issues
Shows what went wrong

Individual Scripts

rebuild_cef_fix.bat

Just rebuilds plugin
Doesn't install
Use for build verification only

diagnose.bat (if exists)

Legacy diagnostic script
Use diagnose_cef.bat instead

📁 FILE STRUCTURE

C:\wingman\
│
├── 📄 DOCUMENTATION
│   ├── README.md                      ← Project overview
│   ├── CEF_GPU_FIX_SOLUTION.md       ← Current fix explanation ⭐
│   ├── CEF_GUARDRAILS.md             ← Rules to prevent breakage ⭐
│   ├── COMPLETE_GUIDE.md             ← Deep technical guide
│   ├── GETTING_STARTED.md            ← Beginner tutorial
│   ├── CHECKLIST.md                  ← Verification checklist
│   ├── QUICK_REFERENCE.md            ← Command reference
│   ├── CHANGES.md                    ← What changed
│   └── INDEX.md                      ← This file
│
├── 🔧 SCRIPTS
│   ├── COMPLETE_FIX_AND_TEST.bat     ← All-in-one solution ⭐
│   ├── rebuild_and_install.bat       ← Quick rebuild
│   ├── diagnose_cef.bat              ← Pre-test diagnostics
│   ├── diagnose_after_test.bat       ← Post-test analysis ⭐
│   └── rebuild_cef_fix.bat           ← Build only
│
├── 💾 SOURCE CODE
│   └── Source\
│       ├── PluginProcessor.cpp       ← Audio + createEditor()
│       ├── PluginEditor.cpp          ← CEF UI window
│       ├── CEFApp.cpp                ← CEF initialization ⚠️
│       ├── CEFSchemeManager.cpp      ← URL handler
│       └── CEFResourceHandler.cpp    ← File serving
│
├── 🎨 RESOURCES
│   └── Resources\
│       └── webui\
│           └── index.html            ← Test UI (purple gradient)
│
└── 🏗️ BUILD
    └── build\
        └── Wingman_artefacts\
            └── Release\VST3\
                └── Wingman.vst3\     ← Built plugin

🎯 COMMON TASKS

Task: Build Plugin

cd C:\wingman
COMPLETE_FIX_AND_TEST.bat

Task: Quick Rebuild After Code Change

cd C:\wingman
rebuild_and_install.bat

Task: Check If Plugin Has All Files

cd C:\wingman
diagnose_cef.bat

Task: Diagnose Why Plugin Shows Black Screen

cd C:\wingman
diagnose_after_test.bat

Task: View CEF Logs

notepad C:\temp\cef_debug.txt
notepad C:\temp\cef.log

Task: Clean Rebuild

cd C:\wingman\build
rmdir /s /q Wingman.dir
cd ..
COMPLETE_FIX_AND_TEST.bat

📊 TROUBLESHOOTING DECISION TREE

Plugin loaded in DAW?
│
├─ NO → Check DAW scanned plugin folder
│        Check moduleinfo.json has unique GUIDs
│        Rescan plugins in DAW
│
└─ YES → UI opens?
    │
    ├─ NO → DAW crashes?
    │        Check Windows Event Viewer
    │        Missing VC++ Redistributable?
    │
    └─ YES → What do you see?
        │
        ├─ Black Screen
        │   → Run: diagnose_after_test.bat
        │   → Check: C:\temp\cef_debug.txt
        │   → Issue: Browser not created or GPU failed
        │
        ├─ White Screen
        │   → Run: diagnose_cef.bat
        │   → Check: CEF DLLs present?
        │   → Issue: Files missing or wrong paths
        │
        ├─ JUCE Sliders (Gain/Cutoff/Type)
        │   → Check: PluginProcessor.cpp createEditor()
        │   → Issue: Returns GenericAudioProcessorEditor
        │   → Fix: Return WingmanEditor instead
        │
        └─ Purple Gradient + Sparkle
            → ✅ SUCCESS! CEF is working!

🔍 KEY FILE LOCATIONS

After Building:

Plugin DLL:
C:\wingman\build\Wingman_artefacts\Release\VST3\Wingman.vst3\Contents\x86_64-win\Wingman.vst3

CEF Files:
C:\wingman\build\Wingman_artefacts\Release\VST3\Wingman.vst3\cef\libcef.dll

Web UI:
C:\wingman\build\Wingman_artefacts\Release\VST3\Wingman.vst3\Contents\Resources\webui\index.html

After Installing:

System Install:
C:\Program Files\Common Files\VST3\Wingman.vst3\

Logs (after running):
C:\temp\cef_debug.txt      ← CEF initialization log
C:\temp\cef.log            ← CEF runtime log

⚠️ CRITICAL WARNINGS

For Developers:

NEVER disable GPU if user wants fancy UI
NEVER return GenericAudioProcessorEditor in createEditor()
NEVER use OSR mode (off-screen rendering)
NEVER initialize CEF in constructor (wait for visibilityChanged)
ALWAYS read CEF_GUARDRAILS.md before modifying CEF code

For AI Assistants:

READ CEF_GUARDRAILS.md COMPLETELY before any changes
TEST in real DAW after modifications
RUN diagnose_after_test.bat to verify
NEVER improvise - follow established patterns
ASK if unsure - don't guess and break things

✅ VERIFICATION CHECKLIST

Use this after building to ensure everything works:

Pre-Test (Build Time):

Test (Runtime):

Post-Test (Verification):

C:\temp\cef_debug.txt exists
Shows "CEF INITIALIZED" message
Shows "browser created successfully"
C:\temp\cef.log has minimal errors
No "FAILED" messages in logs
GPU errors are acceptable (fallback works)

🎓 LEARNING RESOURCES

For Complete Beginners:

Start: GETTING_STARTED.md
Build: Run COMPLETE_FIX_AND_TEST.bat
Test: Follow on-screen instructions
Issues: Run diagnose_after_test.bat

For Experienced Developers:

Architecture: COMPLETE_GUIDE.md
Rules: CEF_GUARDRAILS.md
Current Fix: CEF_GPU_FIX_SOLUTION.md
Reference: QUICK_REFERENCE.md

For AI Assistants:

MUST READ: CEF_GUARDRAILS.md ⚠️
Quick Ref: AI_ASSISTANT_GUIDE.md
Technical: COMPLETE_GUIDE.md
Current State: CEF_GPU_FIX_SOLUTION.md

📈 VERSION HISTORY

v2.0 (2025-10-13) - GPU FIX

✅ Enabled GPU acceleration with fallback
✅ Fixed black screen issue
✅ Added comprehensive guardrails
✅ Created complete test suite
✅ Added diagnostic scripts

v1.0 (Previous) - Initial CEF Integration

✅ Basic CEF integration
❌ GPU disabled (caused black screen)
❌ Limited documentation
❌ No guardrails

🆘 GETTING HELP

Quick Help:

Check this INDEX.md for common tasks
Run appropriate diagnostic script
Read relevant documentation

Still Stuck?

Run diagnose_after_test.bat
Check C:\temp\cef_debug.txt
Check C:\temp\cef.log
Read CEF_GUARDRAILS.md for common mistakes
Compare your code with working version

For Future AIs:

Read CEF_GUARDRAILS.md COMPLETELY
Check existing code before suggesting changes
Test changes in real DAW
Run diagnose_after_test.bat to verify
Don't disable features to "fix" issues - fix root cause

🎯 SUCCESS CRITERIA

Your setup is SUCCESSFUL if:

✅ Plugin builds without errors
✅ All files verified by diagnose_cef.bat
✅ Plugin loads in DAW
✅ Purple gradient displays
✅ "Hi, CEF is Working!" visible
✅ Sparkle emoji animating
✅ Can click and interact
✅ Window resizes smoothly
✅ No crashes
✅ cef_debug.txt shows success

📞 QUICK COMMAND REFERENCE

# Complete rebuild and test
COMPLETE_FIX_AND_TEST.bat

# Quick rebuild
rebuild_and_install.bat

# Check files before test
diagnose_cef.bat

# Analyze after test
diagnose_after_test.bat

# View logs
notepad C:\temp\cef_debug.txt
notepad C:\temp\cef.log

# Clean build
cd C:\wingman\build
rmdir /s /q Wingman.dir
cd ..
COMPLETE_FIX_AND_TEST.bat

🎉 READY TO GO!

Everything is set up and documented. Time to build and test!

Start here: COMPLETE_FIX_AND_TEST.bat

Need help: Check this INDEX for relevant documentation

Break something: Read CEF_GUARDRAILS.md to fix it

Good luck! 🚀

FilesExpand file tree

INDEX.md

Latest commit

History

INDEX.md

File metadata and controls

📚 WINGMAN CEF INTEGRATION - COMPLETE INDEX

🚀 QUICK START (NEW USERS)

📖 DOCUMENTATION GUIDE

🆘 I NEED HELP RIGHT NOW!

🎓 I WANT TO UNDERSTAND EVERYTHING

🤖 I'M AN AI ASSISTANT HELPING WITH THIS PROJECT

🔧 SCRIPTS REFERENCE

Build & Install Scripts

Diagnostic Scripts

Individual Scripts

📁 FILE STRUCTURE

🎯 COMMON TASKS

Task: Build Plugin

Task: Quick Rebuild After Code Change

Task: Check If Plugin Has All Files

Task: Diagnose Why Plugin Shows Black Screen

Task: View CEF Logs

Task: Clean Rebuild

📊 TROUBLESHOOTING DECISION TREE

🔍 KEY FILE LOCATIONS

After Building:

After Installing:

⚠️ CRITICAL WARNINGS

For Developers:

For AI Assistants:

✅ VERIFICATION CHECKLIST

Pre-Test (Build Time):

Test (Runtime):

Post-Test (Verification):

🎓 LEARNING RESOURCES

For Complete Beginners:

For Experienced Developers:

For AI Assistants:

📈 VERSION HISTORY

v2.0 (2025-10-13) - GPU FIX

v1.0 (Previous) - Initial CEF Integration

🆘 GETTING HELP

Quick Help:

Still Stuck?

For Future AIs:

🎯 SUCCESS CRITERIA

📞 QUICK COMMAND REFERENCE

🎉 READY TO GO!