feat(ui): add runtime debug overlay

Author: OmarAglan

.github/workflows/windows-ci.yml

@@ -170,6 +170,25 @@ jobs:
         shell: msys2 {0}
         run: ./build/model-consumer/${{ matrix.name }}/PyramidModelConsumer.exe
 
+      - name: Configure standalone UI consumer
+        shell: msys2 {0}
+        run: >-
+          cmake -S Tests/UIConsumer
+          -B build/ui-consumer/${{ matrix.name }}
+          -G Ninja
+          -DCMAKE_BUILD_TYPE=${{ matrix.configuration }}
+          -DCMAKE_C_COMPILER=${{ matrix.compiler_c }}
+          -DCMAKE_CXX_COMPILER=${{ matrix.compiler_cxx }}
+          -DCMAKE_PREFIX_PATH="$PWD/build/install/${{ matrix.name }}"
+
+      - name: Build standalone UI consumer
+        shell: msys2 {0}
+        run: cmake --build build/ui-consumer/${{ matrix.name }} --parallel
+
+      - name: Run standalone UI consumer
+        shell: msys2 {0}
+        run: ./build/ui-consumer/${{ matrix.name }}/PyramidUIConsumer.exe
+
       - name: Upload binaries
         if: always()
         uses: actions/upload-artifact@v4

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-- `Engine/` builds the C++17 `PyramidEngine` library. `Libraries/` owns independently testable `PyramidFoundation`, `PyramidMath`, `PyramidInput`, `PyramidImage`, and `PyramidModel` packages.
+- `Engine/` builds the C++17 `PyramidEngine` library. `Libraries/` owns independently testable `PyramidFoundation`, `PyramidMath`, `PyramidInput`, `PyramidImage`, `PyramidModel`, `PyramidText`, and `PyramidUI` packages.
 - Engine-owned modules are Core, Graphics, and Win32/WGL Platform. Foundational types/logging, math, physical/action input, image codecs, and CPU asset-format parsing must remain outside the engine binary.
 - `Examples/BasicGame` and `Examples/BasicRendering` are the graphical references; `Examples/RTSReference` is reusable game-side support and is not part of the installed engine API.
 - `Tests/PublicApiLinkage.cpp` protects selected public symbols. Focused tests cover platform input state, generic action mapping, reusable camera controllers, game-side RTS interaction, resize behavior, camera/frustum logic, framebuffers, texture loading, spatial updates/queries/configuration/compaction, render bounds, resources/caches, registry handles/manifests, the authoritative entity scene, and scene serialization. `Tests/EntitySceneTests.cpp` protects stable entity IDs, cycle-safe hierarchy transforms, inherited visibility, component attachment, generated renderer/light proxies, and recursive destruction. `Tests/SceneSerializationTests.cpp` protects deterministic version-2 entity/component round trips, exact manifest references, hierarchy validation, and missing/stale resource diagnostics.
@@ -32,7 +32,7 @@ ctest --preset test-gcc-release
 
 - C++17, four spaces, braces on new lines.
 - Types/public methods use `PascalCase`; locals/parameters use `camelCase`; fields use `m_`.
-- Prefer RAII, explicit ownership, and `PYRAMID_LOG_*` diagnostics. CPU model parsing belongs in `Pyramid::Model`; it must not depend on graphics, Win32, OpenGL, or GLAD. Graphics publication must use `ModelResourceImporter` and the existing mesh cache rather than parallel upload ownership. OBJ/MTL changes require positive/negative index, malformed-input, limit, file-resolution, and transactional upload tests. Geometry passed to scenes must use `Mesh`; do not reintroduce raw vertex-array fields on `RenderObject`. Shared reusable geometry should be acquired through the game-owned `ResourceRegistry::Meshes()` cache; do not create parallel uploads for byte-identical mesh specifications. Shared shader programs should be acquired through `ResourceRegistry::Shaders()`; do not mutate cached `ShaderProgram` instances directly or compile identical stage source repeatedly. Shared sampled textures should use `ResourceRegistry::Textures()`; cached `TextureResource` instances are immutable, color space is part of identity, and file changes must be published through transactional reload. Scene renderables should acquire immutable `Material` resources through `ResourceRegistry::Materials()` rather than ad-hoc shader/texture fields; per-draw matrices belong in command-buffer uniforms, not material identity. Platform input must remain backend-neutral at the public API boundary: native messages feed `InputState`, `Game` evaluates generic `InputActionSystem` contexts before updates, and focus loss must release held controls. Never hard-code RTS or other game-specific action names into the input module. Camera controllers must consume configurable named action references, keep physical bindings in examples/games, and distinguish per-frame delta input from time-scaled rate input; reference profiles belong in examples or games. RTS selection, command, unit, ownership, and edge-scroll semantics must remain in game/reference layers rather than `Pyramid::Engine`; focused behavior belongs in `Tests/RTSInteractionTests.cpp`. Long-lived scene and serialized references should use typed registry handles. Handles must stay non-owning, every alias bind/remap/removal must advance its generation, direct cache mutation must invalidate existing handles, and stale handles must resolve to null rather than a replacement resource.
+- Prefer RAII, explicit ownership, and `PYRAMID_LOG_*` diagnostics. CPU model parsing belongs in `Pyramid::Model`; it must not depend on graphics, Win32, OpenGL, or GLAD. Graphics publication must use `ModelResourceImporter` and the existing mesh cache rather than parallel upload ownership. OBJ/MTL changes require positive/negative index, malformed-input, limit, file-resolution, and transactional upload tests. Geometry passed to scenes must use `Mesh`; do not reintroduce raw vertex-array fields on `RenderObject`. Shared reusable geometry should be acquired through the game-owned `ResourceRegistry::Meshes()` cache; do not create parallel uploads for byte-identical mesh specifications. Shared shader programs should be acquired through `ResourceRegistry::Shaders()`; do not mutate cached `ShaderProgram` instances directly or compile identical stage source repeatedly. Shared sampled textures should use `ResourceRegistry::Textures()`; cached `TextureResource` instances are immutable, color space is part of identity, and file changes must be published through transactional reload. Scene renderables should acquire immutable `Material` resources through `ResourceRegistry::Materials()` rather than ad-hoc shader/texture fields; per-draw matrices belong in command-buffer uniforms, not material identity. Platform input must remain backend-neutral at the public API boundary: native messages feed `InputState`, `Game` evaluates generic `InputActionSystem` contexts before updates, and focus loss must release held controls. Never hard-code RTS or other game-specific action names into the input module. Camera controllers must consume configurable named action references, keep physical bindings in examples/games, and distinguish per-frame delta input from time-scaled rate input; reference profiles belong in examples or games. UI layout, widget state, hit testing, focus, pointer capture, and draw-list generation belong in `Pyramid::UI`; the library must remain independent of OpenGL, Win32, scenes, and game semantics. Debug and game UI must share this runtime rather than introduce parallel systems. `Pyramid::Text` owns renderer-independent glyph metrics and glyph-run generation. UI layers must reserve handled controls with `InputConsumptionMask` before action-context evaluation, and graphics publication must go through `UIRenderer` rather than placing OpenGL calls in `Pyramid::UI`. RTS selection, command, unit, ownership, and edge-scroll semantics must remain in game/reference layers rather than `Pyramid::Engine`; focused behavior belongs in `Tests/RTSInteractionTests.cpp`. Long-lived scene and serialized references should use typed registry handles. Handles must stay non-owning, every alias bind/remap/removal must advance its generation, direct cache mutation must invalidate existing handles, and stale handles must resolve to null rather than a replacement resource.
 - Scene authoring must use `Entity` plus components; do not reintroduce `SceneNode` or make `RenderObject` transforms authoritative. Renderer/light proxies are generated from the scene. Stable entity IDs and hierarchy invariants must remain serialization-safe.
 - Do not add required interface methods with silent no-op defaults.
 - Do not expose source-tree absolute paths through installed target interfaces.

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Pyramid Engine are documented here. The project is pre-al
 
 ## [Unreleased]
 
+### Owned UI foundation and runtime debug overlay
+
+- Added independently installable `PyramidText` and `PyramidUI` targets exported as `Pyramid::Text` and `Pyramid::UI`; both remain platform and renderer independent.
+- Added a deterministic embedded ASCII debug atlas, glyph metrics, text measurement, multiline glyph-run generation, and a white atlas texel for solid UI geometry without runtime font files.
+- Added hybrid UI contexts whose immediate widget facade reconciles retained element state, stable scoped IDs, vertical/horizontal flow layout, clipping, focus, pointer capture, keyboard navigation, DPI metadata, and batched renderer-independent draw lists.
+- Added panels, labels, value rows, separators, spacers, buttons, checkboxes, float sliders, progress bars, and textured-image widgets with configurable themes.
+- Added `InputConsumptionMask` and pre-action UI-context registration in `Game`, preventing handled mouse, wheel, drag, and focused keyboard controls from leaking into gameplay action contexts.
+- Added graphics-device scissor operations plus `UIRenderer` for batched colored/textured quads, embedded-font rendering, conservative DPI-scaled clip rectangles, alpha blending, registered UI textures, and deterministic baseline-state restoration.
+- Added resource-specific UI-renderer initialization rollback and non-canonical `ShaderCache::RemoveAlias()`, preserving unrelated cache-only shaders and textures when GPU buffer allocation fails.
+- Added an F1 `BasicGame` overlay with live frame, render, resource, input, UI, animation, and camera controls.
+- Added standalone installed `Pyramid::UI` consumer validation and focused `Text.DebugFont`, `UI.Context`, input-consumption, and `Graphics.UIRenderer` coverage; CTest now registers 46 targets.
+
 ### Build fixes
 
 - Fixed `WindowResizeEventTests` after the input-library extraction by linking it to `Pyramid::Input`, which propagates the required input and foundation headers.

CMake/PyramidEngineConfig.cmake.in

@@ -7,6 +7,8 @@ find_dependency(PyramidMath CONFIG)
 find_dependency(PyramidImage CONFIG)
 find_dependency(PyramidInput CONFIG)
 find_dependency(PyramidModel CONFIG)
+find_dependency(PyramidText CONFIG)
+find_dependency(PyramidUI CONFIG)
 
 include("${CMAKE_CURRENT_LIST_DIR}/PyramidEngineTargets.cmake")
 check_required_components(PyramidEngine)

CMake/PyramidTextConfig.cmake.in

@@ -0,0 +1,8 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+find_dependency(PyramidFoundation CONFIG)
+find_dependency(PyramidMath CONFIG)
+
+include("${CMAKE_CURRENT_LIST_DIR}/PyramidTextTargets.cmake")
+check_required_components(PyramidText)

CMake/PyramidUIConfig.cmake.in

@@ -0,0 +1,10 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+find_dependency(PyramidFoundation CONFIG)
+find_dependency(PyramidMath CONFIG)
+find_dependency(PyramidInput CONFIG)
+find_dependency(PyramidText CONFIG)
+
+include("${CMAKE_CURRENT_LIST_DIR}/PyramidUITargets.cmake")
+check_required_components(PyramidUI)

CMakeLists.txt

@@ -40,6 +40,8 @@ add_subdirectory(Libraries/PyramidMath)
 add_subdirectory(Libraries/PyramidImage)
 add_subdirectory(Libraries/PyramidInput)
 add_subdirectory(Libraries/PyramidModel)
+add_subdirectory(Libraries/PyramidText)
+add_subdirectory(Libraries/PyramidUI)
 add_subdirectory(Engine)
 
 if(PYRAMID_BUILD_EXAMPLES OR PYRAMID_BUILD_TESTS)
@@ -70,7 +72,7 @@ install(
         PATTERN "*.hpp"
 )
 
-foreach(library IN ITEMS PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel)
+foreach(library IN ITEMS PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel PyramidText PyramidUI)
     install(
         DIRECTORY "${PROJECT_SOURCE_DIR}/Libraries/${library}/include/"
         DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
@@ -89,7 +91,7 @@ install(
     ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}" COMPONENT PyramidEngine
 )
 
-foreach(library IN ITEMS PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel)
+foreach(library IN ITEMS PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel PyramidText PyramidUI)
     install(
         TARGETS ${library}
         EXPORT ${library}Targets
@@ -107,7 +109,7 @@ install(
     COMPONENT PyramidEngine
 )
 
-foreach(library IN ITEMS PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel)
+foreach(library IN ITEMS PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel PyramidText PyramidUI)
     install(
         EXPORT ${library}Targets
         FILE ${library}Targets.cmake
@@ -119,7 +121,7 @@ endforeach()
 
 include(CMakePackageConfigHelpers)
 
-foreach(package IN ITEMS PyramidEngine PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel)
+foreach(package IN ITEMS PyramidEngine PyramidFoundation PyramidMath PyramidImage PyramidInput PyramidModel PyramidText PyramidUI)
     configure_package_config_file(
         "${PROJECT_SOURCE_DIR}/CMake/${package}Config.cmake.in"
         "${PROJECT_BINARY_DIR}/${package}Config.cmake"

Engine/CMakeLists.txt

@@ -30,6 +30,8 @@ target_link_libraries(PyramidEngine
         Pyramid::Input
         Pyramid::Image
         Pyramid::Model
+        Pyramid::Text
+        Pyramid::UI
 )
 
 if(WIN32)

Engine/Core/include/Pyramid/Core/Game.hpp

@@ -2,7 +2,9 @@
 #include <Pyramid/Graphics/GraphicsDevice.hpp>
 #include <Pyramid/Platform/Window.hpp> // Added for std::unique_ptr<Window>
 #include <Pyramid/Input/InputActions.hpp>
+#include <Pyramid/UI/UI.hpp>
 #include <memory>
+#include <vector>
 
 namespace Pyramid {
 
@@ -143,6 +145,13 @@ class Game
 
     Renderer::RenderSystem* GetRenderSystem() const { return m_renderSystem; }
 
+    /**
+     * Register a non-owning UI context for pre-action input capture. The context
+     * must outlive its registration and should be unregistered before destruction.
+     */
+    void RegisterUIContext(UI::Context* context);
+    void UnregisterUIContext(UI::Context* context);
+
     /**
      * @brief Whether the window currently has a non-zero renderable client area.
      */
@@ -155,6 +164,7 @@ class Game
     std::unique_ptr<IGraphicsDevice> m_graphicsDevice;
     std::unique_ptr<ResourceRegistry> m_resourceRegistry;
     InputActionSystem m_inputActions;
+    std::vector<UI::Context*> m_uiContexts;
     Camera* m_activeCamera;
     Renderer::RenderSystem* m_renderSystem;
     bool m_isRunning;

Engine/Core/source/Game.cpp

@@ -196,6 +196,22 @@ namespace Pyramid
         }
     }
 
+    void Game::RegisterUIContext(UI::Context* context)
+    {
+        if (!context || std::find(m_uiContexts.begin(), m_uiContexts.end(), context) != m_uiContexts.end())
+        {
+            return;
+        }
+        m_uiContexts.push_back(context);
+    }
+
+    void Game::UnregisterUIContext(UI::Context* context)
+    {
+        m_uiContexts.erase(
+            std::remove(m_uiContexts.begin(), m_uiContexts.end(), context),
+            m_uiContexts.end());
+    }
+
     void Game::HandleWindowResize(const WindowResizeEvent& event)
     {
         m_renderSurfaceAvailable = event.HasRenderableArea();
@@ -282,9 +298,21 @@ namespace Pyramid
             // Clamp delta time to prevent large jumps (e.g., when debugging or system lag)
             deltaTime = (std::min)(deltaTime, maxDeltaTime);
 
+            // Give retained UI contexts first refusal over physical controls so
+            // clicks, wheel input and focused keyboard navigation do not leak into
+            // lower-priority gameplay action contexts.
+            InputConsumptionMask uiConsumption;
+            for (UI::Context* context : m_uiContexts)
+            {
+                if (context)
+                {
+                    uiConsumption.Merge(context->PrepareInput(GetInput()));
+                }
+            }
+
             // Evaluate engine-generic action contexts from the completed native
             // input snapshot before game logic reads named actions.
-            m_inputActions.Update(GetInput());
+            m_inputActions.Update(GetInput(), uiConsumption);
 
             // Update game logic
             onUpdate(deltaTime);