ROADMAP.md

CMakeLists.txt

@@ -300,6 +300,17 @@ set(WORKFLOW_SOURCES
     src/services/impl/workflow_runtime_config_step.cpp
 )
 
+set(FRAME_WORKFLOW_SOURCES
+    src/services/impl/workflow_frame_begin_step.cpp
+    src/services/impl/workflow_frame_physics_step.cpp
+    src/services/impl/workflow_frame_scene_step.cpp
+    src/services/impl/workflow_frame_render_step.cpp
+    src/services/impl/workflow_frame_audio_step.cpp
+    src/services/impl/workflow_frame_gui_step.cpp
+    src/services/impl/frame_workflow_step_registrar.cpp
+    src/services/impl/frame_workflow_service.cpp
+)
+
 set(MATERIALX_SCRIPT_SOURCES
     src/services/impl/materialx_path_resolver.cpp
     src/services/impl/materialx_search_path_builder.cpp
@@ -316,6 +327,7 @@ if(BUILD_SDL3_APP)
             src/events/event_bus.cpp
             ${JSON_CONFIG_SOURCES}
             ${WORKFLOW_SOURCES}
+            ${FRAME_WORKFLOW_SOURCES}
             ${MATERIALX_SCRIPT_SOURCES}
             src/services/impl/config_compiler_service.cpp
             src/services/impl/command_line_service.cpp

docs/CRASH_ANALYSIS.md

@@ -63,7 +63,7 @@ The crash occurs when:
 ### 3. Code Issues Identified
 
 #### Issue 1: Missing Error Handling in LoadTextureFromFile
-**File**: [bgfx_graphics_backend.cpp:698-744](src/services/impl/bgfx_graphics_backend.cpp#L698-L744)
+**File**: [bgfx_graphics_backend.cpp:698-744](../src/services/impl/bgfx_graphics_backend.cpp#L698-L744)
 
 ```cpp
 bgfx::TextureHandle handle = bgfx::createTexture2D(...);
@@ -80,7 +80,7 @@ return handle;  // ⚠️ PROBLEM: Returns invalid handle anyway!
 **Fix**: Should throw exception or use fallback texture on failure.
 
 #### Issue 2: No Validation of bgfx::copy() Result
-**File**: [bgfx_graphics_backend.cpp:720](src/services/impl/bgfx_graphics_backend.cpp#L720)
+**File**: [bgfx_graphics_backend.cpp:720](../src/services/impl/bgfx_graphics_backend.cpp#L720)
 
 ```cpp
 const bgfx::Memory* mem = bgfx::copy(pixels, size);
@@ -93,7 +93,7 @@ bgfx::TextureHandle handle = bgfx::createTexture2D(..., mem);
 **Fix**: Validate `mem != nullptr` before proceeding.
 
 #### Issue 3: No Texture Dimension Validation
-**File**: [bgfx_graphics_backend.cpp:707-717](src/services/impl/bgfx_graphics_backend.cpp#L707-L717)
+**File**: [bgfx_graphics_backend.cpp:707-717](../src/services/impl/bgfx_graphics_backend.cpp#L707-L717)
 
 ```cpp
 stbi_uc* pixels = stbi_load(path.c_str(), &width, &height, &channels, STBI_rgb_alpha);
@@ -109,7 +109,7 @@ if (!pixels || width <= 0 || height <= 0) {
 **Fix**: Query `bgfx::getCaps()->limits.maxTextureSize` and validate.
 
 #### Issue 4: CreateSolidTexture Fallback Not Validated
-**File**: [bgfx_graphics_backend.cpp:858-860](src/services/impl/bgfx_graphics_backend.cpp#L858-L860)
+**File**: [bgfx_graphics_backend.cpp:858-860](../src/services/impl/bgfx_graphics_backend.cpp#L858-L860)
 
 ```cpp
 binding.texture = LoadTextureFromFile(binding.sourcePath, samplerFlags);
@@ -271,15 +271,15 @@ The crash is most likely caused by:
 
 ## Files Modified
 
-- [tests/bgfx_texture_loading_test.cpp](tests/bgfx_texture_loading_test.cpp) - New investigation tests
-- [CMakeLists.txt:521-530](CMakeLists.txt#L521-L530) - Added test target
+- [tests/bgfx_texture_loading_test.cpp](../tests/bgfx_texture_loading_test.cpp) - New investigation tests
+- [CMakeLists.txt:521-530](../CMakeLists.txt#L521-L530) - Added test target
 
 ## References
 
-- Log analysis: [sdl3_app.log:580-611](sdl3_app.log#L580-L611)
-- Texture loading: [bgfx_graphics_backend.cpp:698-744](src/services/impl/bgfx_graphics_backend.cpp#L698-L744)
-- Pipeline creation: [bgfx_graphics_backend.cpp:804-875](src/services/impl/bgfx_graphics_backend.cpp#L804-L875)
-- Shader validation: [shader_pipeline_validator.cpp](src/services/impl/shader_pipeline_validator.cpp)
+- Log analysis: [sdl3_app.log:580-611](../sdl3_app.log#L580-L611)
+- Texture loading: [bgfx_graphics_backend.cpp:698-744](../src/services/impl/bgfx_graphics_backend.cpp#L698-L744)
+- Pipeline creation: [bgfx_graphics_backend.cpp:804-875](../src/services/impl/bgfx_graphics_backend.cpp#L804-L875)
+- Shader validation: [shader_pipeline_validator.cpp](../src/services/impl/shader_pipeline_validator.cpp)
 
 ▶ Running: build-ninja/sdl3_app -j config/seed_runtime.json
 

docs/FIXES_IMPLEMENTED.md

@@ -8,7 +8,7 @@ This document summarizes all fixes implemented to address the system crash issue
 
 ### 1. Enhanced Error Handling in LoadTextureFromFile ✓
 
-**File**: [src/services/impl/bgfx_graphics_backend.cpp:698-775](src/services/impl/bgfx_graphics_backend.cpp#L698-L775)
+**File**: [src/services/impl/bgfx_graphics_backend.cpp:698-775](../src/services/impl/bgfx_graphics_backend.cpp#L698-L775)
 
 **Changes**:
 
@@ -64,7 +64,7 @@ if (!bgfx::isValid(handle)) {
 
 ### 2. Robust Texture Binding Validation in CreatePipeline ✓
 
-**File**: [src/services/impl/bgfx_graphics_backend.cpp:871-943](src/services/impl/bgfx_graphics_backend.cpp#L871-L943)
+**File**: [src/services/impl/bgfx_graphics_backend.cpp:871-943](../src/services/impl/bgfx_graphics_backend.cpp#L871-L943)
 
 **Changes**:
 
@@ -125,7 +125,7 @@ entry->textures.push_back(std::move(binding));
 
 ### 3. Memory Budget Tracking System ✓
 
-**File**: [src/services/impl/bgfx_graphics_backend.hpp:54-84](src/services/impl/bgfx_graphics_backend.hpp#L54-L84)
+**File**: [src/services/impl/bgfx_graphics_backend.hpp:54-84](../src/services/impl/bgfx_graphics_backend.hpp#L54-L84)
 
 **New Class Added**:
 ```cpp
@@ -156,7 +156,7 @@ private:
 ### 4. Memory Tracking in Pipeline Lifecycle ✓
 
 #### DestroyPipeline
-**File**: [src/services/impl/bgfx_graphics_backend.cpp:964-988](src/services/impl/bgfx_graphics_backend.cpp#L964-L988)
+**File**: [src/services/impl/bgfx_graphics_backend.cpp:964-988](../src/services/impl/bgfx_graphics_backend.cpp#L964-L988)
 
 ```cpp
 for (const auto& binding : it->second->textures) {
@@ -171,7 +171,7 @@ for (const auto& binding : it->second->textures) {
 ```
 
 #### DestroyPipelines
-**File**: [src/services/impl/bgfx_graphics_backend.cpp:1149-1168](src/services/impl/bgfx_graphics_backend.cpp#L1149-L1168)
+**File**: [src/services/impl/bgfx_graphics_backend.cpp:1149-1168](../src/services/impl/bgfx_graphics_backend.cpp#L1149-L1168)
 
 **Benefit**: Properly accounts for memory when textures are destroyed, preventing memory leak accounting.
 
@@ -258,22 +258,22 @@ Trace: shaderKey=wall, textureUniform=node_image_file, stage=2
 
 ## Files Modified
 
-1. **[src/services/impl/bgfx_graphics_backend.hpp](src/services/impl/bgfx_graphics_backend.hpp)**
+1. **[src/services/impl/bgfx_graphics_backend.hpp](../src/services/impl/bgfx_graphics_backend.hpp)**
    - Added `TextureMemoryTracker` class (lines 54-84)
    - Added `memorySizeBytes` to `TextureBinding` struct (line 94)
    - Added `textureMemoryTracker_` member (line 163)
 
-2. **[src/services/impl/bgfx_graphics_backend.cpp](src/services/impl/bgfx_graphics_backend.cpp)**
+2. **[src/services/impl/bgfx_graphics_backend.cpp](../src/services/impl/bgfx_graphics_backend.cpp)**
    - Enhanced `LoadTextureFromFile` with all validations (lines 698-775)
    - Improved `CreatePipeline` texture binding logic (lines 871-943)
    - Updated `DestroyPipeline` to free memory (lines 964-988)
    - Updated `DestroyPipelines` to free memory (lines 1149-1168)
 
-3. **[tests/bgfx_texture_loading_test.cpp](tests/bgfx_texture_loading_test.cpp)** (NEW)
+3. **[tests/bgfx_texture_loading_test.cpp](../tests/bgfx_texture_loading_test.cpp)** (NEW)
    - Created investigation tests documenting crash cause
    - 7 tests covering memory analysis and code review
 
-4. **[CMakeLists.txt](CMakeLists.txt)**
+4. **[CMakeLists.txt](../CMakeLists.txt)**
    - Added `bgfx_texture_loading_test` target (lines 520-530)
 
 5. **[CRASH_ANALYSIS.md](CRASH_ANALYSIS.md)** (NEW)

docs/PROMPT.md

@@ -0,0 +1,51 @@
+Always build and test. 
+Maintain the full testing pyramid: unit tests, static analysis, 
+linters, integration tests, and end-to-end coverage. 
+Continuously execute against the roadmap.
+
+Keep files small and focused. 
+Target <100 LOC per file unless there is a clear and 
+documented reason otherwise. 
+Enforce one responsibility per file.
+
+Decompose aggressively. 
+Break up large blobs of logic into composable units. 
+Large files are a smell.
+
+Use structured architecture. 
+Prefer plugin / service / controller patterns with explicit dependency injection.
+
+Favor declarative designs. 
+Declarative workflows are strongly preferred over imperative glue code.
+
+Everything as a workflow. 
+If something is not part of a workflow, question whether it should be executed at all. 
+Even complex systems (including game engines) can be expressed this way.
+
+Eliminate repetition. 
+Loop, parameterize, and abstract instead of copy-pasting similar code.
+
+Externalize data. 
+If you see a list, map, or configuration embedded in code, 
+it likely belongs in JSON (or equivalent).
+
+Modular configuration. 
+If JSON files grow large, 
+split them and reference them hierarchically.
+
+Ship templates, not chores. 
+Package concepts as reusable templates instead of forcing users to configure from scratch.
+
+Logging is mandatory. 
+Use structured logging with clear 
+levels (DEBUG / INFO / TRACE / ERROR) throughout the system.
+
+Declarative workflows first. 
+Increase usage wherever possible.
+
+Innovate continuously. 
+Avoid stagnation; improve structure, clarity, and expressiveness over time.
+
+Roadmap discipline. 
+If you run out of ROADMAP.md tasks, stop and report. 
+We should reassess priorities before inventing work.

src/services/impl/workflow_frame_physics_step.cpp

@@ -1,6 +1,8 @@
 #include "workflow_frame_physics_step.hpp"
 #include "workflow_step_io_resolver.hpp"
 
+#include "../interfaces/i_physics_service.hpp"
+
 #include <stdexcept>
 
 namespace sdl3cpp::services::impl {

src/services/impl/workflow_frame_physics_step.hpp

@@ -2,10 +2,13 @@
 
 #include "../interfaces/i_workflow_step.hpp"
 #include "../interfaces/i_logger.hpp"
-#include "../interfaces/i_physics_service.hpp"
 
 #include <memory>
 
+namespace sdl3cpp::services {
+class IPhysicsService;
+}
+
 namespace sdl3cpp::services::impl {
 
 class WorkflowFramePhysicsStep final : public IWorkflowStep {