Caffeine

ProjectStartupDialog + File Picker Implementation - Session Summary

Historical Last updated:

Date: May 16, 2026
Status: ✅ Complete & Deployed
Branch: 121-44-audio-preview-spatial-placement
Commits: 27 commits (10 new in final phase)


🎯 Objective#

Implement a complete project startup dialog system with:

  • 3-tab interface (Create New, Open Recent, Browse Projects)
  • Cross-platform file picker with fallback support
  • Toast notification system
  • Proper ImGui state management
  • Zero assertion errors on startup

📋 What We Built#

1. Toast Notification System#

  • Custom Toast struct with types: Success, Error, Info
  • Auto-dismiss after 3 seconds
  • Max 3 visible toasts
  • Color-coded rendering
  • Full integration in main render loop

Files: ProjectStartupDialog.hpp/cpp

2. ProjectStartupDialog Refactor#

3-Tab Interface:

  • Create New Tab:

    • Project name input with validation
    • Template selection
    • File picker for project location selection
    • Create button with error handling
  • Open Recent Tab:

    • Lists recent projects from ProjectManager
    • Search/filter by project name
    • "Show All" toggle for collapsed view
    • Open button for selected project
  • Browse Projects Tab:

    • Directory path input field
    • Browse button (triggers file picker)
    • Results list of projects found
    • Open button for selected project

Files: ProjectStartupDialog.hpp/cpp

3. FilePicker Class (NEW)#

Cross-platform file/folder picker with:

  • Three Modes: PickFolder, PickFile, SaveFile

  • Features:

    • ImGui-based dialog
    • Directory navigation with "Go Up" button
    • File/folder search and filtering
    • Double-click to enter directories
    • Proper sorting (dirs first, alphabetical)
    • Per-dialog state tracking (no cross-contamination)
  • State Management:

    • Static unordered_map<title, State> for multiple picker instances
    • wasJustClosed flag to prevent re-initialization on cancellation
    • Always calls ImGui::End() regardless of Begin() return

Files: FilePicker.hpp, FilePicker.cpp


🐛 Critical Bugs Fixed#

1. ImGui Drag-Drop Assertion Crash#

Problem: ProjectStartupDialog didn't close when project selected, causing multiple render loop iterations with inconsistent ImGui state.
Fix: Set m_open = false when project is selected.
Commit: 107ed2c

2. ImGui Window State Machine Error#

Problem: ImGui::Begin() requires matching ImGui::End() even if Begin() returns false.
Fix: Restructured file picker window to always call ImGui::End().
Commit: ec1a61b

3. ImGui ID Conflicts#

Problem: Multiple items in project lists had ID collisions causing rendering issues.
Fix: Wrapped items with PushID()/PopID() for unique scoping.
Commit: feea0ee

4. File Picker State Contamination#

Problem: Static variables caused state bleeding between multiple picker instances.
Fix: Switched to per-dialog state tracking with unordered_map<title, State>.
Commit: ba207d4

5. File Picker Re-opening After Cancel#

Problem: Picker re-initialized immediately after user cancellation.
Fix: Added wasJustClosed flag to defer state cleanup by one frame.
Commit: 67e85c5


📂 Files Modified/Created#

text
src/editor/
├── ProjectStartupDialog.hpp      (+ state vars, methods)
├── ProjectStartupDialog.cpp      (+ tabs, logic, toasts)
├── FilePicker.hpp               (NEW: interface)
├── FilePicker.cpp               (NEW: ImGui implementation)
├── ProjectManager.hpp/cpp       (GetRecentProjects integration)
└── AudioPreviewPanel.cpp        (drag-drop context verification)

apps/
└── doppio/main.cpp              (ProjectStartupDialog loop)

build/
└── CMakeLists.txt               (+ FilePicker.cpp, CF_HAS_IMGUI flag)

✅ Verification & Testing#

Component Build Runtime Assertions Features
Toast System ✅ ✅ ✅ ✅
Tab Architecture ✅ ✅ ✅ ✅
Create Tab ✅ ✅ ✅ ✅
Recent Tab ✅ ✅ ✅ ✅
Browse Tab ✅ ✅ ✅ ✅
FilePicker ✅ ✅ ✅ ✅
SceneEditor Launch ✅ ✅ ✅ ✅

Build Status: Clean make -j8 doppio
Runtime: Zero assertion errors on startup
Full Workflow: Create → File picker → Project creation → SceneEditor open ✅


🔑 Key Code Patterns#

File Picker Usage (Create Tab)#

cpp
if (m_showLocationPicker) {
    auto path = FilePicker::pickPath(FilePicker::Mode::PickFolder, 
                                     "Select Project Location", 
                                     m_selectedLocation);
    if (path.has_value()) {
        m_selectedLocation = path.value().string();
        m_showLocationPicker = false;
        showToast("Location selected!", ToastType::Success);
    }
}

Dialog Closure (Critical Fix)#

cpp
if (result.has_value()) {
    m_open = false;  // PREVENTS ASSERTION CRASH
}
return result;

ImGui ID Scoping (Project Lists)#

cpp
ImGui::PushID((int)i);
if (ImGui::Selectable(projName.c_str(), selected)) { ... }
ImGui::SameLine();
if (ImGui::Button("Open", ImVec2(70, 0))) { ... }
ImGui::PopID();

📊 Commit History (This Session)#

text
107ed2c fix: close ProjectStartupDialog when project is selected
feea0ee fix: ImGui ID conflicts in Open Recent and Browse tabs
ec1a61b fix: call ImGui::End() regardless of Begin() return value
67e85c5 fix: prevent file picker from re-opening after cancellation
6096d96 fix: file picker state management and integration
ba207d4 fix: prevent state pollution between multiple file pickers
27177fc feat: implement file picker for project creation and browsing
4f1031f feat: implement Browse Projects tab with results list
690affe feat: implement Open Recent tab with search filtering
6e7b7f9 feat: add recent projects state variables to ProjectStartupDialog

Branch History: 27 commits ahead of main
Latest Push: ✅ Successful to 121-44-audio-preview-spatial-placement


🚀 Ready for Production#

  • ✅ All features implemented and tested
  • ✅ No compilation errors or warnings
  • ✅ No runtime assertion errors
  • ✅ Code follows existing codebase patterns
  • ✅ ImGui state management correct
  • ✅ Cross-platform file picker with fallback
  • ✅ All changes committed and pushed

Next Steps: Ready for code review and merge to main branch.


💡 Technical Decisions#

  1. ImGui-Based File Picker (vs native dialogs)

    • Rationale: Works on any platform without rewriting code
    • Fallback for environments without native support
    • Full control over UX
  2. Per-Dialog State Tracking (vs global static)

    • Rationale: Prevents state contamination between multiple picker instances
    • Enables simultaneous multiple pickers
    • Cleaner memory management
  3. Toast Notification System (vs status bar)

    • Rationale: Non-blocking user feedback
    • Multiple notifications visible simultaneously
    • Auto-dismiss reduces UI clutter
  4. Tab-Based UI (vs separate dialogs)

    • Rationale: Single cohesive interface for project management
    • Better UX than multiple windows
    • Aligns with modern editor conventions

Session Completed Successfully ✅