ProjectStartupDialog Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Create a blocking modal dialog that lets users create new projects or open existing ones before the Doppio editor starts.
Architecture: ProjectStartupDialog is a separate component with data layer (always compiled) and UI layer (CF_HAS_IMGUI guarded). It uses ProjectManager for all file operations (create, load, save). Dialog blocks main.cpp startup until user selects a project. SceneEditor::init() is updated to accept ProjectConfig instead of hardcoding "assets" path.
Tech Stack: C++20, ImGui (for UI), ProjectManager (existing), std::filesystem
Task 1: Create ProjectStartupDialog header#
Files:
- Create:
doppio-archived/src/doppio/editor/ProjectStartupDialog.hpp
Step 1: Write the header file
#pragma once
#include "core/Types.hpp"
#include "editor/ProjectManager.hpp"
#include <optional>
#include <string>
namespace Caffeine::Editor {
// ============================================================================
// ProjectStartupDialog — Project selection/creation modal for editor startup
//
// Usage:
// ProjectStartupDialog dialog;
// dialog.init();
// while (dialog.isOpen()) {
// imgui.beginFrame();
// if (auto config = dialog.render()) {
// // User selected or created a project
// SceneEditor.init(config.value());
// break;
// }
// imgui.endFrame();
// }
// ============================================================================
class ProjectStartupDialog {
public:
ProjectStartupDialog();
~ProjectStartupDialog() = default;
// Non-copyable
ProjectStartupDialog(const ProjectStartupDialog&) = delete;
ProjectStartupDialog& operator=(const ProjectStartupDialog&) = delete;
// Initialize dialog (loads recent projects, prepares UI state)
void init();
// Render dialog each frame
// Returns ProjectConfig if user selected/created a project
// Returns std::nullopt if dialog still open
// Modal blocks interaction with other windows
std::optional<ProjectConfig> render();
// Check if dialog is still open
bool isOpen() const { return m_open; }
// Close dialog without selecting project (user quit)
void close() { m_open = false; }
private:
// ── UI state ────────────────────────────────────────────────────────
bool m_open = true;
int m_activeTab = 0; // 0=Create, 1=Recent, 2=Browse
// ── Create tab state ────────────────────────────────────────────────
char m_projectName[256] = {0};
int m_templateIndex = 0; // 0=Empty, 1=2D, 2=3D
std::string m_selectedLocation;
bool m_locationPicked = false;
char m_errorMessage[512] = {0};
bool m_showError = false;
// ── Browse tab state ────────────────────────────────────────────────
std::string m_browsePath;
std::vector<std::filesystem::path> m_browseResults;
// ── ProjectManager for file operations ────────────────────────────
ProjectManager m_projectManager;
// ── UI helpers ────────────────────────────────────────────────────
#ifdef CF_HAS_IMGUI
void renderCreateTab();
void renderRecentTab();
void renderBrowseTab();
void renderErrorPopup();
void setError(const char* message);
#endif
// ── Helper methods ────────────────────────────────────────────────
std::optional<ProjectConfig> tryCreateProject();
std::optional<ProjectConfig> tryOpenProject(const std::filesystem::path& path);
};
} // namespace Caffeine::Editor
Step 2: Verify it compiles as a header-only stub
The header is self-contained and doesn't require implementation yet. This sets up the interface.
Task 2: Create ProjectStartupDialog implementation (Part 1: Data layer)#
Files:
- Create:
doppio-archived/src/doppio/editor/ProjectStartupDialog.cpp
Step 1: Implement constructor and init()
#include "editor/ProjectStartupDialog.hpp"
#include <filesystem>
namespace Caffeine::Editor {
ProjectStartupDialog::ProjectStartupDialog()
: m_selectedLocation(std::filesystem::path(std::getenv("HOME")).string() + "/Documents/CaffeineProjects") {
m_projectName[0] = '\0';
m_errorMessage[0] = '\0';
}
void ProjectStartupDialog::init() {
// ProjectManager ctor loads recent projects automatically
// (via DefaultRecentPath)
m_locationPicked = false;
}
std::optional<ProjectConfig> ProjectStartupDialog::tryCreateProject() {
// Validate inputs
if (std::string(m_projectName).empty()) {
setError("Project name cannot be empty");
return std::nullopt;
}
// Build project config
ProjectConfig config;
config.Name = m_projectName;
config.RootPath = std::filesystem::path(m_selectedLocation) / m_projectName;
config.TemplateType = (m_templateIndex == 0) ? "Empty" : (m_templateIndex == 1) ? "2D" : "3D";
config.LastScene = "";
// Create via ProjectManager
if (!m_projectManager.CreateNewProject(config)) {
setError("Failed to create project. Check permissions and path.");
return std::nullopt;
}
return config;
}
std::optional<ProjectConfig> ProjectStartupDialog::tryOpenProject(const std::filesystem::path& path) {
ProjectConfig config;
if (!m_projectManager.OpenProject(path)) {
setError("Failed to open project. Invalid project.caffeine file.");
return std::nullopt;
}
return m_projectManager.GetCurrentProject();
}
void ProjectStartupDialog::setError(const char* message) {
if (message) {
std::strncpy(m_errorMessage, message, sizeof(m_errorMessage) - 1);
m_errorMessage[sizeof(m_errorMessage) - 1] = '\0';
}
m_showError = true;
}
} // namespace Caffeine::Editor
Step 2: Verify data layer compiles
This part should compile without ImGui. Test by checking diagnostics.
Task 3: Create ProjectStartupDialog implementation (Part 2: UI layer)#
Files:
- Modify:
doppio-archived/src/doppio/editor/ProjectStartupDialog.cpp(add UI render methods)
Step 1: Add render() main entry point
#ifdef CF_HAS_IMGUI
#include <imgui.h>
#endif
std::optional<ProjectConfig> ProjectStartupDialog::render() {
#ifdef CF_HAS_IMGUI
if (!m_open) return std::nullopt;
ImGuiWindowFlags flags = ImGuiWindowFlags_Modal
| ImGuiWindowFlags_AlwaysAutoResize
| ImGuiWindowFlags_NoMove
| ImGuiWindowFlags_NoResize;
ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(), ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
if (ImGui::Begin("Doppio Project Manager", nullptr, flags)) {
ImGui::Text("Welcome to Doppio — Select or Create a Project");
ImGui::Separator();
if (ImGui::BeginTabBar("ProjectTabs")) {
if (ImGui::BeginTabItem("Create New")) {
renderCreateTab();
ImGui::EndTabItem();
}
if (ImGui::BeginTabItem("Recent Projects")) {
renderRecentTab();
ImGui::EndTabItem();
}
if (ImGui::BeginTabItem("Browse")) {
renderBrowseTab();
ImGui::EndTabItem();
}
ImGui::EndTabBar();
}
ImGui::Separator();
if (ImGui::Button("Quit Doppio", ImVec2(120, 0))) {
m_open = false;
return std::nullopt;
}
renderErrorPopup();
ImGui::End();
}
return std::nullopt;
#else
// Non-ImGui fallback
m_open = false;
return std::nullopt;
#endif
}
Step 2: Implement renderCreateTab()
#ifdef CF_HAS_IMGUI
void ProjectStartupDialog::renderCreateTab() {
ImGui::InputText("Project Name", m_projectName, sizeof(m_projectName));
ImGui::SameLine();
ImGui::HelpMarker("Name for your new project");
const char* templates[] = {"Empty", "2D", "3D"};
ImGui::Combo("Template##CreateTab", &m_templateIndex, templates, IM_ARRAYSIZE(templates));
ImGui::SameLine();
ImGui::HelpMarker("Project template (affects initial folder structure)");
ImGui::Text("Location: %s", m_selectedLocation.c_str());
if (ImGui::Button("Browse Location...##Create")) {
// For now, use simple folder browser dialog
// TODO: Implement native file picker or ImGui folder browser
m_locationPicked = true;
}
ImGui::Spacing();
ImGui::Separator();
if (ImGui::Button("Create & Open", ImVec2(150, 0))) {
if (auto config = tryCreateProject()) {
m_open = false;
return;
}
}
}
#endif
Wait - need to handle the render return properly. Let me revise:
#ifdef CF_HAS_IMGUI
void ProjectStartupDialog::renderCreateTab() {
ImGui::InputText("Project Name", m_projectName, sizeof(m_projectName));
ImGui::SameLine();
ImGui::HelpMarker("Name for your new project");
const char* templates[] = {"Empty", "2D", "3D"};
ImGui::Combo("Template##CreateTab", &m_templateIndex, templates, IM_ARRAYSIZE(templates));
ImGui::Text("Location: %s", m_selectedLocation.c_str());
if (ImGui::Button("Browse Location...##Create")) {
m_locationPicked = true;
}
ImGui::Spacing();
ImGui::Separator();
if (ImGui::Button("Create & Open", ImVec2(150, 0))) {
if (auto config = tryCreateProject()) {
m_open = false;
// Note: actual return happens in render() after this frame
}
}
}
#endif
Actually, need to refactor render() to track selected project:
std::optional<ProjectConfig> ProjectStartupDialog::render() {
#ifdef CF_HAS_IMGUI
if (!m_open) return std::nullopt;
ImGuiWindowFlags flags = ImGuiWindowFlags_Modal
| ImGuiWindowFlags_AlwaysAutoResize
| ImGuiWindowFlags_NoMove;
ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(), ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
ImGui::SetNextWindowSize(ImVec2(600, 400), ImGuiCond_FirstUseEver);
std::optional<ProjectConfig> result;
if (ImGui::Begin("Doppio Project Manager", nullptr, flags)) {
ImGui::Text("Welcome to Doppio — Select or Create a Project");
ImGui::Separator();
if (ImGui::BeginTabBar("ProjectTabs")) {
if (ImGui::BeginTabItem("Create New")) {
result = renderCreateTab();
ImGui::EndTabItem();
}
if (ImGui::BeginTabItem("Recent Projects")) {
result = renderRecentTab();
ImGui::EndTabItem();
}
if (ImGui::BeginTabItem("Browse")) {
result = renderBrowseTab();
ImGui::EndTabItem();
}
ImGui::EndTabBar();
}
ImGui::Separator();
if (ImGui::Button("Quit Doppio", ImVec2(120, 0))) {
m_open = false;
}
renderErrorPopup();
ImGui::End();
}
if (result) {
m_open = false;
}
return result;
#else
return std::nullopt;
#endif
}
And update tab render methods to return optional:
#ifdef CF_HAS_IMGUI
std::optional<ProjectConfig> ProjectStartupDialog::renderCreateTab() {
ImGui::InputText("Project Name", m_projectName, sizeof(m_projectName));
ImGui::SameLine();
ImGui::HelpMarker("Name for your new project");
const char* templates[] = {"Empty", "2D", "3D"};
ImGui::Combo("Template##CreateTab", &m_templateIndex, templates, IM_ARRAYSIZE(templates));
ImGui::Text("Location: %s", m_selectedLocation.c_str());
if (ImGui::Button("Browse Location...##Create")) {
m_locationPicked = true;
}
ImGui::Spacing();
ImGui::Separator();
if (ImGui::Button("Create & Open", ImVec2(150, 0))) {
return tryCreateProject();
}
return std::nullopt;
}
std::optional<ProjectConfig> ProjectStartupDialog::renderRecentTab() {
if (m_projectManager.GetRecentProjects().empty()) {
ImGui::TextDisabled("No recent projects. Create a new one or browse.");
return std::nullopt;
}
ImGui::BeginChild("RecentList", ImVec2(0, 300), true);
for (const auto& recent : m_projectManager.GetRecentProjects()) {
if (ImGui::Selectable(recent.string().c_str())) {
return tryOpenProject(recent);
}
}
ImGui::EndChild();
return std::nullopt;
}
std::optional<ProjectConfig> ProjectStartupDialog::renderBrowseTab() {
static char browsePath[256] = {0};
ImGui::InputText("Search Path", browsePath, sizeof(browsePath));
if (ImGui::Button("Browse...")) {
// TODO: Implement file picker
}
ImGui::Text("Browse for project.caffeine files");
ImGui::BeginChild("BrowseList", ImVec2(0, 300), true);
// TODO: List project files
ImGui::EndChild();
return std::nullopt;
}
void ProjectStartupDialog::renderErrorPopup() {
if (m_showError) {
ImGui::OpenPopup("ProjectError");
m_showError = false;
}
if (ImGui::BeginPopupModal("ProjectError", nullptr, ImGuiWindowFlags_AlwaysAutoResize)) {
ImGui::TextWrapped("%s", m_errorMessage);
ImGui::Separator();
if (ImGui::Button("OK", ImVec2(120, 0))) {
ImGui::CloseCurrentPopup();
}
ImGui::EndPopup();
}
}
#endif
Step 3: Update header to match return types
Update the private method signatures to return optional:
#ifdef CF_HAS_IMGUI
private:
std::optional<ProjectConfig> renderCreateTab();
std::optional<ProjectConfig> renderRecentTab();
std::optional<ProjectConfig> renderBrowseTab();
void renderErrorPopup();
void setError(const char* message);
#endif
Task 4: Update CMakeLists.txt to include new component#
Files:
- Modify:
CMakeLists.txt(editor sources section)
Step 1: Add ProjectStartupDialog to editor sources
Find the section that lists editor source files and add:
# In src/CMakeLists.txt or main CMakeLists.txt editor section:
# Find existing lines like:
# src/editor/ProjectManager.cpp
# src/editor/SceneEditor.cpp
# Add after ProjectManager:
src/editor/ProjectStartupDialog.cpp
Step 2: Verify CMake regeneration
Run: cmake .. in build directory
Expected: No "ProjectStartupDialog" not found errors
Task 5: Update SceneEditor::init() signature#
Files:
- Modify:
doppio-archived/src/doppio/editor/SceneEditor.hpp(init method) - Modify:
doppio-archived/src/doppio/editor/SceneEditor.cpp(init implementation)
Step 1: Update header
Change from:
#ifdef CF_HAS_SDL3
bool init(RHI::RenderDevice* device, Assets::AssetManager* assetManager,
const char* assetsPath = "assets");
#endif
To:
#ifdef CF_HAS_SDL3
bool init(RHI::RenderDevice* device, Assets::AssetManager* assetManager,
const ProjectConfig& projectConfig);
#endif
Step 2: Update implementation
Change from:
bool SceneEditor::init(RHI::RenderDevice* device, Assets::AssetManager* assetManager,
const char* assetsPath) {
if (!m_viewport.init(device)) return false;
m_assetBrowser.init(assetsPath); // ← Use projectConfig.AssetRawPath instead
// ...
}
To:
bool SceneEditor::init(RHI::RenderDevice* device, Assets::AssetManager* assetManager,
const ProjectConfig& projectConfig) {
if (!m_viewport.init(device)) return false;
m_assetBrowser.init(projectConfig.AssetRawPath.string().c_str());
m_currentProjectConfig = projectConfig;
// ...
}
Step 3: Add member variable to SceneEditor
In SceneEditor.hpp private section:
private:
ProjectConfig m_currentProjectConfig; // ← Add this
Task 6: Update main.cpp to use ProjectStartupDialog#
Files:
- Modify:
apps/doppio/main.cpp
Step 1: Add include
Add after other editor includes:
#include "editor/ProjectStartupDialog.hpp"
Step 2: Show dialog before SceneEditor init
Replace this section (lines 44-64):
Caffeine::Assets::AssetManager assetManager(nullptr, "assets");
Caffeine::Render::Camera2D editorCamera;
Caffeine::Editor::ImGuiIntegration imgui;
if (!imgui.init(window, &device)) {
// ...
}
Caffeine::Editor::SceneEditor editor;
if (!editor.init(&device, &assetManager)) {
// ...
}
With:
Caffeine::Assets::AssetManager assetManager(nullptr, "assets");
Caffeine::Render::Camera2D editorCamera;
Caffeine::Editor::ImGuiIntegration imgui;
if (!imgui.init(window, &device)) {
std::fprintf(stderr, "ImGuiIntegration::init failed\n");
device.shutdown();
SDL_DestroyWindow(window);
SDL_Quit();
return 1;
}
// Show project startup dialog
Caffeine::Editor::ProjectStartupDialog projectDialog;
projectDialog.init();
Caffeine::Editor::ProjectConfig selectedProject;
bool projectSelected = false;
while (projectDialog.isOpen() && !projectSelected) {
SDL_Event event;
while (SDL_PollEvent(&event)) {
imgui.processEvent(event);
if (event.type == SDL_EVENT_QUIT) {
imgui.shutdown();
device.shutdown();
SDL_DestroyWindow(window);
SDL_Quit();
return 0; // User quit
}
}
Caffeine::RHI::CommandBuffer* cmd = device.beginFrame();
if (!cmd) continue;
imgui.beginFrame();
if (auto config = projectDialog.render()) {
selectedProject = config.value();
projectSelected = true;
}
imgui.prepareRender(cmd);
Caffeine::RHI::RenderPassDesc passDesc;
passDesc.clearColor[0] = 0.10f;
passDesc.clearColor[1] = 0.10f;
passDesc.clearColor[2] = 0.12f;
passDesc.clearColor[3] = 1.00f;
cmd->beginRenderPass(passDesc);
imgui.endFrame(cmd);
cmd->endRenderPass();
device.endFrame(cmd);
}
if (!projectSelected) {
imgui.shutdown();
device.shutdown();
SDL_DestroyWindow(window);
SDL_Quit();
return 0;
}
// Create asset manager with project's asset path
Caffeine::Assets::AssetManager assetManager(nullptr, selectedProject.AssetRawPath.string().c_str());
Caffeine::Editor::SceneEditor editor;
if (!editor.init(&device, &assetManager, selectedProject)) {
std::fprintf(stderr, "SceneEditor::init failed\n");
imgui.shutdown();
device.shutdown();
SDL_DestroyWindow(window);
SDL_Quit();
return 1;
}
Task 7: Add #include in SceneEditor.hpp#
Files:
- Modify:
doppio-archived/src/doppio/editor/SceneEditor.hpp
Step 1: Add ProjectManager include
Add after other editor includes:
#include "editor/ProjectManager.hpp"
Task 8: Verify compilation and test#
Files:
- Build and test:
./caffeine-build
Step 1: Clean build
cd build
rm -rf *
cmake ..
make -j8
Expected: All files compile, no linker errors, doppio executable created
Step 2: Run doppio and verify dialog appears
./build/apps/doppio/doppio
Expected:
- Doppio window opens
- Project Manager dialog appears
- Can interact with tabs
- Cannot access editor until project selected
Step 3: Test Create Project workflow
- Click "Create New" tab
- Enter project name "TestProject"
- Keep default template "Empty"
- Click "Create & Open"
- Verify editor opens with project
Task 9: Commit changes#
Step 1: Stage all files
git add \
src/editor/ProjectStartupDialog.hpp \
src/editor/ProjectStartupDialog.cpp \
src/editor/SceneEditor.hpp \
src/editor/SceneEditor.cpp \
apps/doppio/main.cpp \
CMakeLists.txt
Step 2: Commit
git commit -m "feat: add ProjectStartupDialog for project lifecycle management
- New component: ProjectStartupDialog with 3 tabs (Create, Recent, Browse)
- Modal dialog blocks editor startup until project selected
- Integrates with existing ProjectManager for all file operations
- SceneEditor::init() now accepts ProjectConfig instead of hardcoded paths
- main.cpp shows project dialog before editor initialization
- Persists recent projects via ProjectManager
Fixes critical startup flow blocker where editor was hardcoded to 'Untitled'"
Summary#
This plan creates a complete project startup workflow in 9 tasks (2-5 minutes each):
- Header - Define ProjectStartupDialog interface
- Data layer - Implement create/open logic using ProjectManager
- UI layer - Implement 3 tabs with ImGui
- CMake - Register new component in build
- SceneEditor signature - Accept ProjectConfig instead of path
- main.cpp integration - Show dialog before editor init
- Include fix - Add ProjectManager include
- Compilation test - Verify build and runtime behavior
- Commit - Save all changes
Total estimated time: 4-5 hours for complete implementation with testing.