Renderer: add engine-owned debug modes, overlay, and GPU-timing scaffolding

[ercmine]

Motivation

• Provide a canonical, engine-owned renderer debug layer instead of ad-hoc shell toggles to make visualization and instrumentation reliable and extensible.
• Expose debug mode state and overlays through the renderer API so tools and the runtime shell can query/switch modes safely at runtime.
• Capture pass timing and lightweight instrumentation with a robust fallback if backend GPU timers are unavailable.

Description

• Added a new debug subsystem (engine/render/debug_renderer.{hpp,cpp}) that defines RendererDebugMode, counters, per-pass timing (RendererPassTiming), a frame RendererDebugSnapshot, program override bindings, and an encapsulated RendererDebugState with runtime switching and overlay text formatting.
• Extended the public Renderer API (engine/render/renderer.hpp) with debug controls and hooks: set_debug_mode, set_debug_mode_from_index, cycle_debug_mode, set_debug_program_overrides, set_debug_counters, add_debug_pass_timing, and debug_snapshot.
• Integrated engine-owned debug behavior into the bgfx backend (engine/render/bgfx/renderer_bgfx.cpp) so modes are applied at frame begin (dbg text/wireframe flag) and at submit time (program/state overrides for normals, albedo, depth, and overdraw); overdraw uses additive/no-depth state as an approximation.
• Added runtime wiring and sample debug shaders: shell hotkeys (1..8 + Tab) to switch modes, debug shader programs under shaders/debug/renderer_debug/*, and manifest entries in shaders/shaders.cmake; updated docs and README to describe modes and limits.

Testing

• Ran the new unit smoke test by compiling and executing the debug-state test: g++ -std=c++20 -I. tests/render/debug_renderer_tests.cpp engine/render/debug_renderer.cpp && ./a.out which passed successfully and validated mode switching, snapshot, counters, and overlay line generation.
• Updated the renderer lifecycle unit to include debug-mode API smoke assertions (tests/render/renderer_lifecycle_tests.cpp) and added render_debug_renderer_tests to CMake test wiring so the new test will run under CI when dependencies are configured.
• Full CMake configure/build with --preset linux-debug could not be completed in this environment due to missing platform dependencies (SDL3/bgfx roots), so the integrated shader compilation and end-to-end runtime validation were not executed here (this is expected in the current CI environment and logged in build output).

---

Codex Task