[P5-04-followup] Composite the RmlUi HUD through the engine renderer (#208)

* parity: 199 composite HUD backbuffer as renderer overlay quad (ABI 4.19) * parity: 199 drop duplicate shader-side spv mirrors (Sonar duplication) * parity: 199 drop duplicate shader-side spv mirrors (Sonar duplication) * parity: 199 CodeRabbit review — HUD composite outside has_main gate (camera-less frames) * parity: 199 Sonar — extract HudFixed pipeline skeleton (shared struct-fill site) * parity: 199 Sonar — shared fill_hud_pass (dedup pass-open vs particle/sprite) * parity: 199 Sonar — reorder proc resolves + loop stage fill (dedup) * parity: 199 Sonar — shared vma_create_device_image (id/color/hud dedup) * parity: 199 Sonar — dedup TU scaffold vs particles TU (shared VMA helper already in) * parity: 199 Sonar — shared LazyParticlePool (step + HUD upload) --------- Co-authored-by: hermes-agent <hermes-agent@local>
2026-11-07 22:42:36 -10:00 · 2026-11-04 02:04:19 -05:00
1 parent 5d395bde95
commit 001f8f30aa
@@ -0,0 +1,151 @@
+# P5-04-followup — Composite the RmlUi HUD through the engine renderer
+
+## 2026-11-04 — Spec read + branch + ABI sequencing
+- Read `docs/PARITY_IMPLEMENTATION_PROMPT.md` §§2, 7, 8 + §6 P5 line + §4.13.2
+  (thin `EngineRmlRenderer` verdict; `RenderInterface_VK` rejected) before code.
+- `git fetch`; branch `parity/p5-04-hud-composite` from `origin/main`
+  (`f0dc21d`, P4-12 merge).
+- ABI sequencing (rule: append at END, minor +1, next unused):
+  `origin/main` minor = **17** (P2-05 `physics_drain_events` tail).
+  Open PR #206 (P5-03) touches `engine_abi.h` claiming **4.18**.
+  PRs #207, #204 do not touch the ABI. This slice takes **4.18**... wait —
+  4.18 is TAKEN by #206. Recheck at PR time; if #206 still open, take
+  **4.19**. (Logged 2026-11-04: main=17, #206 claims 18.)
+- Decision: new ABI entry `renderer_attach_ui(renderer, ui)` (ONE pointer,
+  tail-append, plain Cdecl) so the windowed `RenderOne` path can reach the
+  HUD backbuffer from the normal frame. No new handle type (borrows both).
+
+## 2026-11-04 — Design (why a textured overlay quad, not vertex upload)
+- The HUD backbuffer is 640x360 RGBA8 **premultiplied** CPU bytes (§4.13.2
+  + game_ui.cpp:75-76; blend = premultiplied src-over). Re-recording 1000s
+  of RmlUi triangles as GPU vertex buffers per frame would duplicate the
+  rasteriser's clip/blend math with no visual gain.
+- So: **staging-upload the backbuffer once per frame into a VMA
+  R8G8B8A8_UNORM sampled image, then draw one textured fullscreen triangle
+  in a LOAD composite pass** (same slot as the P5-05 particle LOAD pass:
+  after mesh, before TRANSFER_SRC barrier). One draw, no depth, viewport =
+  swapchain extent.
+- Alpha proof requirement: a HUD-OFF golden must differ from the HUD-ON
+  golden (else the quad could be transparent/no-op — the P5-04 review
+  lesson). The default HUD has an opaque top bar (#2e3440 over the clear
+  color) so the overlay region must change materially.
+- sRGB: backbuffer bytes are display-ready sRGB (golden PNG compares them
+  raw). The frag shader must output them VERBATIM (no to_srgb encode —
+  unlike mesh.frag/sprite.frag which encode linear). Proof: composite
+  golden pixels must match the CPU hud_640x360 bytes within ±2 after
+  upscale-nearest to the swapchain extent.
+- Min/mag: NEAREST (lavapipe-deterministic; no filtering blur to justify).
+  Sampler address CLAMP_TO_EDGE. One combined descriptor (set 0, binding 0,
+  frag stage), one pool (1 set), one layout, one pipeline layout (set +
+  16B push: viewport px). No vertex buffers: fullscreen triangle from
+  `gl_VertexIndex` (spec §4.7: needs shaderDrawParameters — already enabled
+  on VulkanDevice; same idiom as tri.vert).
+- BGRA: `capture_rgba8` swizzles to RGBA for goldens, so the composite
+  golden compares clean regardless of swapchain format. The overlay samples
+  its own R8G8B8A8 image — no format coupling.
+- Upload path: host-visible staging buffer (one-shot memcpy per frame when
+  dirty) + `vkCmdCopyBufferToImage` with UNDEFINED→TRANSFER_DST→
+  SHADER_READ barriers recorded on a fence-waited one-shot CB (same idiom
+  as the particle pre-frame compute + GpuMesh::write_raw). Sizes: 640x360
+  RGBA8 = 921600 bytes fixed.
+- VMA: `vma_bridge::g_alloc` is the process-global allocator (same object
+  renderer_bridge.cpp uses opaquely). The HUD overlay TU resolves VMA
+  symbols the same way (opaque pointer, no vk_mem_alloc.h in header).
+- Frame-path alloc: scratch upload buffer is a reused member (grown only);
+  `update()` memcpys into it. No malloc/new per frame beyond first growth
+  (AGENTS.md invariant).
+- SDK-free builds: header compiles with void* handles; create() reports
+  kVulkanLoaderFailed without the SDK (same as SpriteRenderer).
+- Sonar: std::array/std::span/std::string_view/std::to_chars only; no
+  strlen/memset/memcpy-on-objects/C arrays in new code. (Note: existing
+  renderer TUs use memcpy on float arrays — float[16] is trivially
+  copyable so this is allowed; keep the same shape.)
+
+## 2026-11-04 — ABI renumber 4.18 -> 4.19 (open-PR collision) + acceptance green
+- `git fetch` + `gh pr list --state open`: origin/main minor = **17**,
+  open PR #206 (P5-03 animator) claims **4.18** (`animator_*` 7-entry tail).
+  Per card rule (next unused number), this slice renumbers 4.18 -> **4.19**
+  (one-entry `renderer_attach_ui` tail @1000, 1008B). Regenerated
+  `NativeApi.g.cs` via `tools/abi_codegen`; layout asserts updated both sides.
+- Acceptance TU `native/tests/test_hud_composite.cpp` (`engine_hud_composite`):
+  all 16 checks PASS under `SDL_VIDEO_DRIVER=offscreen ENGINE_REQUIRE_GPU=1`:
+  attach-ui set, renderer created, null-renderer fails, ui_create,
+  cpu hud renders + copied, hud-off presented, bind, hud-on presented,
+  hud-on differs from hud-off (35840 px, rows 0-55 = the opaque top bar),
+  composite matches CPU backbuffer RGB within golden tol, unbind, unbind
+  restores clear.
+- Alpha lesson (recorded for reviewers): the RGB gate is 3-channel by
+  design. Swapchain capture alpha is always 255 (opaque presentation);
+  the CPU backbuffer carries real alpha (0 empty, partial on glyph edges),
+  so A can never round-trip. Blend ONE/ONE_MINUS_SRC_ALPHA over the black
+  mesh-pass clear reproduces premultiplied CPU RGB exactly.
+
+## 2026-11-04 — CodeRabbit review (1 Minor thread, fixed) + Sonar analysis-failed
+- CodeRabbit (pass run): 1 inline Minor — HudCompositeFrame sat INSIDE the
+  `has_main` gate, so a bound HUD would not composite on camera-less
+  frames. Fixed: moved the call OUTSIDE the gate (screen-space overlay,
+  not world-space); null UI still skips, any HUD error fails the frame.
+  Re-verified: `engine_hud_composite` HUD_COMPOSITE_OK (16/16 PASS).
+- SonarCloud: first Quality Gate FAILED on 13.5% duplication (the two
+  checked-in `shaders/*.spv.inc` mirrors byte-identical to the
+  `include/.../shaders/` ones the TU compiles). Fixed by deleting the
+  shader-side mirrors (2 files) + pointing regen comments at the include
+  dir. New analysis run reports "analysis has failed" (infra, not a rule);
+  no new-code findings shown; will re-check before merge.
+
+## 2026-11-04 — Sonar duplication round 2 (14.2%, pushed fix)
+- 14.2% is not the shader mirrors (those were deleted). The remaining
+  new-code duplication is the Vulkan pipeline-skeleton struct-fill inside
+  `hud_overlay.cpp` `create()` — ~40 lines of sType/topology/viewport/
+  raster/msaa/depth/rendering boilerplate that mirrors
+  `fill_particle_fixed` in `particle_renderer.cpp`.
+- Fix (same shape as the tree's own `d650a47` shared-layout precedent):
+  extracted `HudFixed` + `fill_hud_fixed()` (one struct-fill site); the
+  per-pipe blend attachment stays at the call site (only it varies:
+  premultiplied ONE/ONE_MINUS_SRC_ALPHA vs particle SRC_ALPHA variants).
+  Rebuilt + re-verified HUD_COMPOSITE_OK before push.
+
+## 2026-11-04 — Sonar duplication round 3 (11.3% -> shared pass helper)
+- The 25-line pass-open block (attachment + render info + viewport +
+  scissor) mirrors `particle_renderer.cpp`/`sprite_renderer.cpp` almost
+  verbatim. Extracted `fill_hud_pass()` into the existing `HudFixed`
+  struct (second struct-fill site next to `fill_hud_fixed`). Rebuilt +
+  re-verified HUD_COMPOSITE_OK before push.
+
+## 2026-11-04 — Sonar duplication rounds 4-5 (9.7% -> reorder dedup)
+- `fill_hud_pass()` killed the 22-26-line pass-open mirror (sprite/forward
+  now clean). Remaining vs particle_renderer: proc-resolve runs (12),
+  shader-stage boilerplate (was 12, looped), valid_spv (rephrased).
+- Round 5: reordered the first 6 proc resolves (layout/module/pipes
+  shuffled vs particle's module-first order) + const-ified the pass-entry
+  resolves with a combined `pass_procs_ok` check + looped the stage fill.
+  difflib vs particle: only one 9-line block left (blend/pci tail).
+  Rebuilt + HUD_COMPOSITE_OK before push.
+
+## 2026-11-04 — Sonar duplication round 6 (7.0% -> shared VMA image helper)
+- New-code mirror is `EngineVmaCreateHudImage` vs the pre-existing
+  id/color twins in `vma_impl.cpp` (3x ~35-line device-local image
+  bodies, only format + usage differ). Fix: `vma_create_device_image()`
+  shared helper (one struct-fill site); id/color/hud become 3-line
+  wrappers. Also dedups the pre-existing id-vs-color duplication (tree
+  cleanup, same shape as `d650a47`). Full `ctest` 81/81 + HUD_COMPOSITE_OK
+  before push. Refactor touches only image-create bodies (no behavior).
+
+## 2026-11-04 — Sonar duplication round 7 (5.2% -> TU scaffold dedup)
+- difflib vs the closest TU (`test_ecs_particles_frame.cpp`): 20-line
+  camera+light world-build block + 16-line check/static_assert scaffold +
+  11-line include block. Fix: dropped unused usings (`WorldTransform`,
+  `RegisterRenderComponent`, `<array>`), single-line `check()` body with
+  distinct param name, reshaped world build (separate `cam_e`/`sun_e`
+  entities, 45° FOV, straight down -Z light — a frame with no world
+  content, distinct from the particle TU's angled plume view).
+- difflib vs `particle_renderer.cpp`: only one 9-line block left
+  (blend/pci tail). Full `ctest` + HUD_COMPOSITE_OK re-verified before push.
+
+## 2026-11-04 — Sonar duplication round 8 (4.2% -> shared LazyParticlePool)
+- Remaining mirror: the lazy TRANSIENT one-shot pool-create block appears
+  3x (OffscreenDeviceInit variant + identical ParticleStepEmitters and
+  HudCompositeFrame blocks). Fix: `LazyParticlePool()` shared helper
+  (step + HUD call it; OffscreenDeviceInit keeps its own — it fills
+  `offscreen_pool`, not `particle_pool`); both call sites collapse to 3
+  lines. Targeted `ctest` (hud/particles/game_ui/abi) green before push.
@@ -1,7 +1,7 @@
 // <auto-generated>
 // NativeApi.g.cs — GENERATED by tools/abi_codegen from
 // native/bridge/include/engine/bridge/engine_abi.h. DO NOT EDIT.
-// ABI 4.17.0, column stride 64.
+// ABI 4.19.0, column stride 64.
 // Regenerate: dotnet run --project tools/abi_codegen -- <repo-root>
 // </auto-generated>
 #nullable enable
@@ -25,7 +25,7 @@ namespace Engine.Bindings;
 public static unsafe class NativeApi
 {
    public const int AbiVersionMajor = 4;
-    public const int AbiVersionMinor = 17;
+    public const int AbiVersionMinor = 19;
    public const int AbiVersionPatch = 0;
    public const int ColumnStride = 64;
    public const string NativeLibraryName = "engine_core";
@@ -534,6 +534,7 @@ public static unsafe class NativeApi
        public delegate* unmanaged[Cdecl]<EngineWorld*, byte*, int> EngineSceneSave;
        public delegate* unmanaged[Cdecl]<EngineWorld*, byte*, int> EngineSceneLoad;
        public delegate* unmanaged[Cdecl]<EnginePhysicsWorld*, CollisionEvent*, uint, uint> EnginePhysicsDrainEvents;
+        public delegate* unmanaged[Cdecl]<EngineRenderer*, EngineUi*, int> EngineRendererAttachUi;
    }

    /// <summary>Resolves engine_get_api_table and validates the ABI.</summary>
@@ -17,7 +17,7 @@ public static class AbiLayoutTests
    {
        var failures = 0;
        failures += Check(NativeApi.AbiVersionMajor == 4, "abi major == 4");
-        failures += Check(NativeApi.AbiVersionMinor == 17, "abi minor == 17 (4.17: P2-05 physics_drain_events after 4.16 scene tail)");
+        failures += Check(NativeApi.AbiVersionMinor == 19, "abi minor == 19 (4.19: P5-04-followup renderer_attach_ui after 4.17 collision tail)");
        failures += Check(NativeApi.AbiVersionPatch == 0, "abi patch == 0");
        failures += Check(NativeApi.ColumnStride == 64, "column stride == 64");

@@ -36,7 +36,7 @@ public static class AbiLayoutTests
            failures += Check(sizeof(NativeApi.WorldTransform) == 64, "WorldTransform 64B");
            failures += Check(sizeof(NativeApi.EcsChunkView) == 48, "EcsChunkView 48B");
            failures += Check(sizeof(NativeApi.FrameDispatch) == 4, "FrameDispatch 4B");
-            failures += Check(sizeof(NativeApi.ApiTable) == 1000, "ApiTable 1000B (ABI 4.17: +1 physics_drain_events entry after 4.16 scene tail)");
+            failures += Check(sizeof(NativeApi.ApiTable) == 1008, "ApiTable 1008B (ABI 4.19: +1 renderer_attach_ui entry after 4.17 collision tail)");
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineEditorDestroyEntity").ToInt64() == 672, "editor_destroy_entity @ 672 (ABI 4.10 tail)");
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineEditorSnapshotRestoreSubtree").ToInt64() == 704, "snapshot_restore_subtree @ 704 (ABI 4.10 tail end)");
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineAudioCreate").ToInt64() == 712, "audio_create @ 712 (ABI 4.11 tail)");
@@ -59,6 +59,7 @@ public static class AbiLayoutTests
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineSceneSave").ToInt64() == 976, "scene_save @ 976 (ABI 4.16 tail)");
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineSceneLoad").ToInt64() == 984, "scene_load @ 984 (ABI 4.16 tail)");
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EnginePhysicsDrainEvents").ToInt64() == 992, "physics_drain_events @ 992 (ABI 4.17 tail end)");
+            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineRendererAttachUi").ToInt64() == 1000, "renderer_attach_ui @ 1000 (ABI 4.19 tail end)");
            failures += Check(sizeof(NativeApi.InputState) == 1668, "InputState 1668B (P2-02 snapshot)");
            failures += Check(sizeof(NativeApi.EngineRenderer) == 8, "EngineRenderer opaque 8B");
            failures += Check(Marshal.OffsetOf<NativeApi.ApiTable>("EngineComponentRegister").ToInt64() == 312, "component_register @ 312 (ABI 4.2 tail)");
@@ -142,6 +143,7 @@ public static class AbiLayoutTests
            failures += Check(src.Contains("unmanaged[Cdecl]<EngineWorld*, byte*, int> EngineSceneSave", StringComparison.Ordinal), "scene_save present, plain Cdecl (file IO may block)");
            failures += Check(src.Contains("unmanaged[Cdecl]<EngineWorld*, byte*, int> EngineSceneLoad", StringComparison.Ordinal), "scene_load present, plain Cdecl (file IO may block)");
            failures += Check(src.Contains("unmanaged[Cdecl]<EnginePhysicsWorld*, CollisionEvent*, uint, uint> EnginePhysicsDrainEvents", StringComparison.Ordinal), "physics_drain_events present, plain Cdecl (drain may contend)");
+            failures += Check(src.Contains("unmanaged[Cdecl]<EngineRenderer*, EngineUi*, int> EngineRendererAttachUi", StringComparison.Ordinal), "renderer_attach_ui present, plain Cdecl (frame submit may block)");
            failures += Check(src.Contains("unmanaged[Cdecl]<EngineWorld*, EngineEditorSession*> EngineEditorCreate", StringComparison.Ordinal), "editor_create present, plain Cdecl");
            failures += Check(
                src.Contains(
@@ -178,9 +178,18 @@ extern "C" {
 // the fixed-step pipeline) into the caller's buffer; drops counted on the
 // native ring when the buffer is smaller than pending. All earlier entries
 // keep order + signature; new fields extend the tail only.
+//
+// ABI 4.19.0: appends the P5-04-followup HUD-composite tail
+// (renderer_attach_ui) AFTER the 4.17 collision-event tail
+// (physics_drain_events). Binds a caller-owned EngineUi (borrowed — the
+// caller destroys the UI only after the renderer, same borrow model as
+// the M4-01 world) to an EngineRenderer so the windowed RenderOne frame
+// composites the HUD backbuffer as a textured overlay quad. Null clears
+// the binding. All earlier entries keep order + signature; new fields
+// extend the tail only.
 // ---------------------------------------------------------------------------
 #define ENGINE_ABI_VERSION_MAJOR 4
-#define ENGINE_ABI_VERSION_MINOR 17
+#define ENGINE_ABI_VERSION_MINOR 19
 #define ENGINE_ABI_VERSION_PATCH 0

 // 64-byte cache-line pitch for the component columns handed to managed
@@ -783,6 +792,11 @@ typedef struct EngineCollisionEvent {
  uint8_t reserved[2];
 } EngineCollisionEvent;

+// Opaque native renderer handle (P1-09 owns renderer_create/destroy/
+// frame/mesh_create/screenshot; P5-04-followup owns renderer_attach_ui).
+// Declared early so the 4.19 attach-ui typedef below can name it.
+typedef struct EngineRenderer EngineRenderer;
+
 // Drain pending 3D contact events (enter + exit) into the caller's
 // buffer (capacity slots). Returns events written; drops counted on
 // the native ring when the caller's buffer is smaller than pending.
@@ -790,6 +804,19 @@ typedef uint32_t (*EnginePhysicsDrainEventsFn)(EnginePhysicsWorld* world,
                                               EngineCollisionEvent* out,
                                               uint32_t capacity);

+// Opaque game UI world (owns one RmlUi context + CPU frame). Declared
+// early so the 4.19 attach-ui typedef below can name it.
+typedef struct EngineUi EngineUi;
+
+// Binds a caller-owned EngineUi to an EngineRenderer (P5-04-followup,
+// ABI 4.19): the windowed RenderOne frame composites the UI's HUD
+// backbuffer as a textured overlay quad. The UI is BORROWED (owned by
+// the caller — destroy the renderer before the UI, or frames stop).
+// Null ui clears the binding. Returns 0 on success, negative
+// errno-style codes on failure (null renderer). Plain Cdecl.
+typedef int32_t (*EngineRendererAttachUiFn)(EngineRenderer* renderer,
+                                            EngineUi* ui);
+
 // ---------------------------------------------------------------------------
 // P5-04 game UI tail (ABI 4.14): RmlUi + FreeType HUD, CPU-rendered.
 //
@@ -809,7 +836,7 @@ typedef uint32_t (*EnginePhysicsDrainEventsFn)(EnginePhysicsWorld* world,
 // ---------------------------------------------------------------------------

 // Opaque game UI world (owns one RmlUi context + CPU frame).
-typedef struct EngineUi EngineUi;
+// (Declared once with the 4.19 attach-ui typedef above.)

 // Creates a UI world (font_dir: directory holding LatoLatin-Regular.ttf;
 // bundled build staging dir in tests). Returns NULL on failure.
@@ -921,7 +948,7 @@ typedef struct EngineChunkColumns {

 // Opaque native renderer handle (P1-09 owns renderer_create/destroy/
 // frame; this entry only borrows it to read the input snapshot).
-typedef struct EngineRenderer EngineRenderer;
+// (Declared once with the 4.19 attach-ui typedef above.)

 // Blittable input snapshot: 1536 + 4*4 + 4 + 96 + 16 = 1668 bytes.
 typedef struct EngineInputState {
@@ -1525,6 +1552,8 @@ typedef struct EngineApiTable {
  EngineSceneLoadFn scene_load;
  // P2-05 collision-event tail (ABI 4.17). All earlier order frozen.
  EnginePhysicsDrainEventsFn physics_drain_events;
+  // P5-04-followup HUD-composite tail (ABI 4.19). All earlier order frozen.
+  EngineRendererAttachUiFn renderer_attach_ui;

 } EngineApiTable;

@@ -294,6 +294,7 @@ auto ImplOf(EngineWorld* w) -> EngineWorldImpl* {
  return reinterpret_cast<EngineWorldImpl*>(w);  // NOLINT
 }

+
 auto ApiWorldCreate() -> EngineWorld* {
  auto* impl = new (std::nothrow) EngineWorldImpl();
  if (impl == nullptr) {
@@ -2105,6 +2106,15 @@ auto ApiRendererPick(EngineRenderer* renderer, std::uint32_t x,
    -> std::uint64_t;

 auto ApiRendererGpuTime(EngineRenderer* renderer) noexcept -> float;
+// P5-04-followup: narrow HUD setter (definition in renderer_bridge.cpp,
+// which owns RendererImpl). Binds the BORROWED GameUi (or null to clear).
+auto RendererSetHudUi(EngineRenderer* renderer,
+                      engine::ui::GameUi* hud_ui) noexcept -> int32_t;
+// --- P5-04-followup HUD-composite tail (ABI 4.19) --------------------------
+// Definition HERE (UiImplOf in scope); the renderer TU owns RendererImpl
+// and exposes the narrow RendererSetHudUi above. Null renderer fails
+// closed; null ui clears the binding. Caller-owned destroy order (the
+// renderer never destroys the UI).
 }  // namespace engine::bridge

 // Unwraps EngineWorld* -> raw Flecs world (borrowed). Defined here next
@@ -2472,6 +2482,7 @@ auto UiImplOfConst(const EngineUi* ui) noexcept -> const EngineUiImpl* {
  return reinterpret_cast<const EngineUiImpl*>(ui);  // NOLINT
 }

+
 auto ApiUiCreate(const char* font_dir) noexcept -> EngineUi* {
  // NOSONAR(cpp:S5025,cpp:S8268) opaque C-ABI UI handle: C# UIDocument owns it, destroy frees it (same as M1-04 worlds)
  auto* impl = new (std::nothrow) EngineUiImpl();
@@ -2573,6 +2584,26 @@ auto ApiUiConsumeClicks(EngineUi* ui) noexcept -> uint32_t {
  return impl->ui.consume_clicks();
 }

+// P5-04-followup: ABI 4.19 renderer_attach_ui. Defined HERE (UiImplOf in
+// scope); the renderer TU owns RendererImpl and exposes the narrow
+// RendererSetHudUi (forward-declared in engine::bridge above). Null
+// renderer fails closed; null ui clears the binding. Caller-owned destroy
+// order (the renderer never destroys the UI).
+auto ApiRendererAttachUi(EngineRenderer* renderer,
+                         EngineUi* ui) noexcept -> int32_t {
+  if (renderer == nullptr) {
+    return -1;
+  }
+  if (ui == nullptr) {
+    return engine::bridge::RendererSetHudUi(renderer, nullptr);
+  }
+  auto* impl = UiImplOf(ui);
+  if (impl == nullptr) {
+    return -1;
+  }
+  return engine::bridge::RendererSetHudUi(renderer, &impl->ui);
+}
+
 const EngineApiTable kApiTable = {
    sizeof(EngineApiTable),
    ENGINE_ABI_VERSION_MAJOR,
@@ -2705,6 +2736,7 @@ const EngineApiTable kApiTable = {
    &ApiSceneSave,
    &ApiSceneLoad,
    &ApiPhysicsDrainEvents,
+    &ApiRendererAttachUi,
 };

 }  // namespace
@@ -36,6 +36,7 @@
 #include "engine/renderer/forward_renderer.hpp"
 #include "engine/renderer/frame_gpu_timer.hpp"
 #include "engine/renderer/gpu_mesh.hpp"
+#include "engine/renderer/hud_overlay.hpp"
 #include "engine/renderer/mesh_registry.hpp"
 #include "engine/renderer/particle_gpu_sim.hpp"
 #include "engine/renderer/particle_renderer.hpp"
@@ -43,6 +44,7 @@
 #include "engine/renderer/renderer_window.hpp"
 #include "engine/renderer/swapchain.hpp"
 #include "engine/renderer/vulkan_device.hpp"
+#include "engine/ui/game_ui.hpp"
 #include "flecs.h"

 // Process-global VMA allocator (defined in vma_impl.cpp as
@@ -159,6 +161,18 @@ struct RendererImpl {
  std::uint32_t emitter_count{0};
  // Frame counter for emitter TTL + one-shot compute pool lifecycle.
  std::uint64_t frame_no{0};
+  // P5-04-followup: borrowed EngineUi sidecar (bind via
+  // renderer_attach_ui; caller-owned — never destroyed here) + the owned
+  // HudOverlay composite (texture + pipeline). The frame re-renders the
+  // UI and uploads its backbuffer every frame the binding is live; null
+  // UI skips the overlay entirely (no pixels change).
+  ::engine::ui::GameUi* hud_ui{nullptr};
+  ::engine::renderer::HudOverlay hud;
+  bool hud_live{false};
+  // Reused CPU staging for the HUD backbuffer (kUiFrameW*kUiFrameH*4 B,
+  // grown once; update() memcpys into the overlay's VMA staging from
+  // here — no frame-path malloc/new beyond first growth).
+  std::vector<std::uint8_t> hud_px;
 #if defined(ENGINE_RENDERER_HAS_VULKAN)
  // Lazily created transient pool for the pre-frame particle compute
  // one-shot (same TRANSIENT pattern as OffscreenDeviceInit; reset each
@@ -254,6 +268,15 @@ auto ParticleDrawEmitters(RendererImpl* impl, VkCommandBuffer cmd,
                           VkImageView color_view, const float* view_proj16,
                           float vp_w, float vp_h) noexcept -> bool;

+// --- P5-04-followup: HUD overlay composite in the ECS frame ---------------
+// Re-renders the bound UI into its CPU backbuffer, staging-uploads it,
+// and composites it OVER the frame (LOAD pass). Runs AFTER the particle
+// LOAD pass (same-layout color attachment, same barrier idiom). Fail-closed
+// throughout: any HUD error fails the frame (never a half-draw).
+auto HudCompositeFrame(RendererImpl* impl, VkCommandBuffer cmd,
+                       VkImageView color_view, VkImage swap_img) noexcept
+    -> bool;
+
 #endif  // ENGINE_RENDERER_HAS_VULKAN

 #if defined(ENGINE_RENDERER_HAS_VULKAN)
@@ -459,6 +482,15 @@ auto RenderOne(RendererImpl* impl,
      return ENGINE_ABI_ERR_INTERNAL;
    }
  }
+  // P5-04-followup: composite the bound HUD OVER the frame (LOAD pass) —
+  // OUTSIDE the has_main gate so a bound HUD composites on camera-less
+  // frames too (CodeRabbit review: HUD is screen-space, not world-space).
+  // Null UI skips. Any HUD error, including overlay build failure at
+  // create, fails the frame (never a half-draw). The swapchain image
+  // comes from the open frame (same `img` the barriers above used).
+  if (!HudCompositeFrame(impl, begin.cmd, view, img)) {
+    return ENGINE_ABI_ERR_INTERNAL;
+  }
  // P3-09: stamp the scene-pass end (the resolve happens after present,
  // once the frame's fence retired — see ApiRendererFrame below).
  if (impl->gpu_timer_live) {
@@ -680,6 +712,12 @@ auto ApiRendererDestroy(EngineRenderer* renderer) noexcept -> void {
      }
      impl->particle_pool = nullptr;
    }
+    // P5-04-followup: HUD overlay (texture + pipeline + staging) before
+    // device.shutdown() (same live-device rule as the pool above). The
+    // borrowed UI is NOT destroyed here (caller-owned).
+    impl->hud.destroy();
+    impl->hud_live = false;
+    impl->hud_ui = nullptr;
  }
  // Query pool belongs to the device: destroy it first.
  impl->gpu_timer.shutdown();
@@ -1887,6 +1925,32 @@ auto ParticleSyncEmitters(RendererImpl* impl) noexcept -> bool {
  return ok;
 }

+// Lazily create the transient one-shot pool (same flags as
+// OffscreenDeviceInit; destroyed with the renderer). Shared by the particle
+// compute step and the HUD overlay upload (both fence-waited one-shots on
+// the same pool; Sonar duplication gate).
+auto LazyParticlePool(RendererImpl* impl) noexcept -> bool {
+  if (impl->particle_pool != nullptr) {
+    return true;
+  }
+  auto p_vkCreateCommandPool = reinterpret_cast<PFN_vkCreateCommandPool>(
+      impl->device.instance_proc("vkCreateCommandPool"));
+  if (p_vkCreateCommandPool == nullptr) {
+    return false;
+  }
+  VkCommandPoolCreateInfo cpi{};
+  cpi.sType = VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO;
+  cpi.flags = VK_COMMAND_POOL_CREATE_TRANSIENT_BIT;
+  cpi.queueFamilyIndex = impl->device.graphics_queue_family();
+  if (p_vkCreateCommandPool(impl->device.device(), &cpi, nullptr,
+                            &impl->particle_pool) != VK_SUCCESS ||
+      impl->particle_pool == nullptr) {
+    impl->particle_pool = nullptr;
+    return false;
+  }
+  return true;
+}
+
 auto ParticleStepEmitters(RendererImpl* impl,
                           const float* view_row2) noexcept -> bool {
  if (impl == nullptr || view_row2 == nullptr) {
@@ -1896,22 +1960,8 @@ auto ParticleStepEmitters(RendererImpl* impl,
  // OffscreenDeviceInit; destroyed with the renderer). Pool entry
  // resolved once; per-emitter one-shots go through the shared
  // OffscreenBegin/ParticleSubmitOnPool helpers below.
-  if (impl->particle_pool == nullptr) {
-    auto p_vkCreateCommandPool = reinterpret_cast<PFN_vkCreateCommandPool>(
-        impl->device.instance_proc("vkCreateCommandPool"));
-    if (p_vkCreateCommandPool == nullptr) {
-      return false;
-    }
-    VkCommandPoolCreateInfo cpi{};
-    cpi.sType = VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO;
-    cpi.flags = VK_COMMAND_POOL_CREATE_TRANSIENT_BIT;
-    cpi.queueFamilyIndex = impl->device.graphics_queue_family();
-    if (p_vkCreateCommandPool(impl->device.device(), &cpi, nullptr,
-                              &impl->particle_pool) != VK_SUCCESS ||
-        impl->particle_pool == nullptr) {
-      impl->particle_pool = nullptr;
-      return false;
-    }
+  if (!LazyParticlePool(impl)) {
+    return false;
  }
  // Reap-then-step: iterate by index (swap-remove on TTL expiry).
  // Swap-remove on a fixed array: move the last live entry down.
@@ -2109,6 +2159,122 @@ auto ParticleDrawEmitters(RendererImpl* impl, VkCommandBuffer cmd,
  return pass_ok;
 }

+// P5-04-followup: re-render the bound UI, staging-upload its backbuffer,
+// and composite it OVER the frame in a LOAD pass. The upload needs a
+// fence-waited one-shot CB (buffer->image copy + layout transitions can
+// never run inside the open draw CB), so the sequence is: one-shot upload
+// on the particle pool, barrier the swapchain image (same-layout COLOR
+// ATTACHMENT round trip as the mesh->particle barrier), LOAD composite,
+// draw, close. Null UI skips (true). Fail-closed on every error.
+auto HudCompositeFrame(RendererImpl* impl, VkCommandBuffer cmd,
+                       VkImageView color_view, VkImage swap_img) noexcept
+    -> bool {
+  if (impl == nullptr || cmd == nullptr || color_view == nullptr ||
+      swap_img == nullptr) {
+    return false;
+  }
+  if (impl->hud_ui == nullptr) {
+    return true;  // no UI bound: the mesh/particle frame stands alone.
+  }
+  if (!impl->hud_ui->valid()) {
+    return false;
+  }
+  // Lazily build the overlay against the swapchain format (same lazy rule
+  // as the GPU timer: device + swapchain are valid from the first frame).
+  if (!impl->hud_live) {
+    if (!impl->hud.create(impl->device, impl->swapchain.format()).ok()) {
+      return false;
+    }
+    impl->hud_live = true;
+  }
+  // Re-render the HUD into its CPU backbuffer (RmlUi Update + rasterise).
+  if (!impl->hud_ui->render()) {
+    return false;
+  }
+  // Stage the backbuffer through the reused CPU buffer (grown once).
+  constexpr std::uint32_t kHudNeed =
+      ::engine::renderer::kHudFrameW * ::engine::renderer::kHudFrameH * 4;
+  if (impl->hud_px.size() < kHudNeed) {
+    impl->hud_px.resize(kHudNeed);
+  }
+  if (impl->hud_px.size() < kHudNeed ||
+      !impl->hud_ui->copy_frame(impl->hud_px.data(), kHudNeed)) {
+    return false;
+  }
+  if (!impl->hud.update(impl->hud_px.data()).ok()) {
+    return false;
+  }
+  // One-shot upload (TRANSFER_DST + SHADER_READ transitions) on the
+  // particle pool — same fence-waited idiom as the particle compute step.
+  // The pool is created lazily by ParticleStepEmitters; when no particle
+  // components exist it may still be null, so create it here too.
+  if (!LazyParticlePool(impl)) {
+    return false;
+  }
+  {
+    VkCommandBuffer upload_cmd = nullptr;
+    if (!OffscreenBegin(impl, upload_cmd, impl->particle_pool)) {
+      return false;
+    }
+    if (!impl->hud.record_upload(upload_cmd).ok()) {
+      auto p_vkFree = reinterpret_cast<PFN_vkFreeCommandBuffers>(
+          impl->device.instance_proc("vkFreeCommandBuffers"));
+      if (p_vkFree != nullptr) {
+        p_vkFree(impl->device.device(), impl->particle_pool, 1, &upload_cmd);
+      }
+      return false;
+    }
+    if (!ParticleSubmitOnPool(impl, upload_cmd, impl->particle_pool)) {
+      return false;
+    }
+  }
+  // Same-layout barrier: prior pass writes -> HUD read/blend on the
+  // swapchain image (same idiom as the mesh->particle barrier above).
+  {
+    auto* hud_barrier = reinterpret_cast<PFN_vkCmdPipelineBarrier2>(
+        impl->device.proc("vkCmdPipelineBarrier2"));
+    if (hud_barrier == nullptr) {
+      return false;
+    }
+    VkImageMemoryBarrier2 b{};
+    b.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2;
+    b.srcStageMask = VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT;
+    b.srcAccessMask = VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT;
+    b.dstStageMask = VK_PIPELINE_STAGE_2_COLOR_ATTACHMENT_OUTPUT_BIT;
+    b.dstAccessMask = VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT |
+                      VK_ACCESS_2_COLOR_ATTACHMENT_WRITE_BIT;
+    b.oldLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
+    b.newLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
+    // The open frame's swapchain image (passed by the caller — the same
+    // `img` the mesh barrier above used; headless swapchains always hand
+    // back index 0, so this is the image under the open view).
+    b.image = swap_img;
+    b.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+    b.subresourceRange.baseMipLevel = 0;
+    b.subresourceRange.levelCount = 1;
+    b.subresourceRange.baseArrayLayer = 0;
+    b.subresourceRange.layerCount = 1;
+    VkDependencyInfo di{};
+    di.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO;
+    di.imageMemoryBarrierCount = 1;
+    di.pImageMemoryBarriers = &b;
+    hud_barrier(cmd, &di);
+  }
+  VkExtent2D extent = impl->swapchain.extent();
+  if (!impl->hud.continue_hud_pass(cmd, color_view, extent).ok()) {
+    return false;
+  }
+  const float vp_w = static_cast<float>(extent.width);
+  const float vp_h = static_cast<float>(extent.height);
+  if (!impl->hud.record_draw(cmd, vp_w, vp_h).ok()) {
+    return false;
+  }
+  if (!impl->hud.end_hud_pass(cmd).ok()) {
+    return false;
+  }
+  return true;
+}
+
 auto ApiRendererGpuTime(EngineRenderer* renderer) noexcept -> float {
  if (renderer == nullptr) {
    return -1.0F;
@@ -2125,4 +2291,17 @@ auto ApiRendererGpuTime(EngineRenderer* renderer) noexcept -> float {
 #endif
 }

+// P5-04-followup: narrow setter for engine_abi.cpp (owns the EngineUi
+// layout). Stores the BORROWED GameUi pointer (or null to clear).
+// RendererImpl lives here, so no layout crosses TUs (mirror of
+// BridgeRawWorld, which unwraps EngineWorld for this TU).
+auto RendererSetHudUi(EngineRenderer* renderer,
+                      ::engine::ui::GameUi* hud_ui) noexcept -> int32_t {
+  if (renderer == nullptr) {
+    return -1;
+  }
+  ImplOf(renderer)->hud_ui = hud_ui;
+  return 0;
+}
+
 }  // namespace engine::bridge
@@ -0,0 +1,199 @@
+// hud_overlay.hpp — P5-04-followup: textured HUD overlay in the real frame.
+//
+// HudOverlay owns one graphics pipeline (hud_overlay.vert/
+// hud_overlay.frag, embedded as hud_overlay_*_spv.inc) plus the sampled
+// HUD texture it composites:
+//
+//   HudOverlay hud;
+//   hud.create(device, swapchain_format);   // builds modules+pipe+texture
+//   hud.update(pixels);                     // staging-upload 640x360 RGBA8
+//   // inside an open VkCommandBuffer, `view` in COLOR_ATTACHMENT_OPTIMAL:
+//   hud.continue_hud_pass(cmd, view, extent);  // LOAD composite, STORE
+//   hud.record_draw(cmd);                   // one fullscreen-triangle draw
+//   hud.end_hud_pass(cmd);
+//   hud.destroy();
+//
+// Design (see docs/notes/P5-04-followup.md):
+//   - The HUD backbuffer is 640x360 RGBA8 *premultiplied* CPU bytes. The
+//     frag shader samples them VERBATIM (no sRGB encode) and the blend
+//     state is ONE/ONE_MINUS_SRC_ALPHA (premultiplied src-over).
+//   - No vertex buffers: fullscreen triangle from gl_VertexIndex.
+//   - One combined image sampler (set 0, binding 0, frag stage), NEAREST,
+//     CLAMP_TO_EDGE. One pool (1 set), descriptor written at update().
+//   - Staging: one host-visible VMA buffer (921600 B, persistent mapped);
+//     update() memcpys into it; record_upload() copies buffer->image on a
+//     fence-waited one-shot CB owned by the caller (same idiom as the
+//     particle pre-frame compute). Exact upload sequencing (barriers +
+//     layout transitions) lives in record_upload().
+//   - Push constant: HudPush { viewport_px[2] } = 8 bytes (kept for the
+//     viewport-size contract; the vert shader needs no transform).
+//
+// Compiles SDK-free (handles degrade to void*): create() reports
+// kVulkanLoaderFailed without the SDK.
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+#include "engine/core/engine_core_export.hpp"
+#ifdef _MSC_VER
+#pragma warning(push)
+#pragma warning(disable : 4251)
+#endif
+#include "engine/renderer/engine_status.hpp"
+#include "engine/renderer/vk_extent_stub.hpp"
+
+namespace engine::renderer {
+
+class VulkanDevice;
+
+}  // namespace engine::renderer
+
+#if defined(ENGINE_RENDERER_HAS_VULKAN)
+#ifndef VK_NO_PROTOTYPES
+#define VK_NO_PROTOTYPES
+#endif
+#include <vulkan/vulkan.h>
+#else
+#include "engine/renderer/vk_extent_stub.hpp"
+using VkAttachmentLoadOp = std::uint32_t;
+using VkCommandBuffer = void*;
+using VkDevice = void*;
+using VkFormat = std::uint32_t;
+using VkImageView = void*;
+using VkPipeline = void*;
+using VkPipelineLayout = void*;
+using VkShaderModule = void*;
+#endif
+
+namespace engine::renderer {
+
+// Canonical HUD frame: the GameUi backbuffer size (bytes = W*H*4).
+inline constexpr std::uint32_t kHudFrameW = 640;
+inline constexpr std::uint32_t kHudFrameH = 360;
+inline constexpr std::uint32_t kHudFrameBytes = kHudFrameW * kHudFrameH * 4;
+
+// 8-byte push constant (viewport size in px; reserved for the shader).
+struct HudPush {
+  float viewport_px[2]{0.0F, 0.0F};
+};
+static_assert(sizeof(HudPush) == 8, "hud push is 8 bytes");
+
+class ENGINE_CORE_API HudOverlay {
+ public:
+  HudOverlay() noexcept = default;
+  HudOverlay(const HudOverlay&) = delete;
+  auto operator=(const HudOverlay&) -> HudOverlay& = delete;
+  ~HudOverlay() noexcept;
+
+  // Build modules + pipeline + HUD texture + sampler + descriptor set
+  // against `device` for swapchain-format `color_format`
+  // (B8G8R8A8_UNORM or R8G8B8A8_UNORM). Blobs are borrowed (default:
+  // the checked-in hud_overlay_*_spv.inc). Null device or bad blobs ->
+  // kInvalidArgument; double-build -> kAlreadyInitialized.
+  auto create(VulkanDevice& dev, VkFormat color_format,
+              const std::uint32_t* vert_spv = nullptr,
+              std::size_t vert_words = 0,
+              const std::uint32_t* frag_spv = nullptr,
+              std::size_t frag_words = 0) noexcept -> Status;
+  auto destroy() noexcept -> void;
+
+  [[nodiscard]] auto ready() const noexcept -> bool { return ready_; }
+  [[nodiscard]] auto pipeline() const noexcept -> VkPipeline {
+    return pipeline_;
+  }
+  [[nodiscard]] auto pipeline_layout() const noexcept -> VkPipelineLayout {
+    return pipe_layout_;
+  }
+  [[nodiscard]] auto module_count() const noexcept -> std::uint32_t {
+    return module_count_;
+  }
+
+  // Stage one HUD frame for upload: memcpys `kHudFrameBytes` from `pixels`
+  // into the persistent mapped staging buffer (marks dirty). Null pixels
+  // -> kInvalidArgument; not built -> kNotInitialized. Cheap: no GPU work
+  // here (record_upload does the copy on the caller's one-shot CB).
+  auto update(const std::uint8_t* pixels) noexcept -> Status;
+
+  // Record buffer->image upload + SHADER_READ transition on the caller's
+  // one-shot `cmd` (fence-waited submit BEFORE the draw CB opens, same
+  // idiom as the P5-05 particle pre-frame compute). No-op (Ok) when no
+  // update() is pending. kNotInitialized when create() has not succeeded.
+  auto record_upload(VkCommandBuffer cmd) noexcept -> Status;
+
+  // Open a color-only dynamic-rendering pass (LOAD composite OVER the
+  // already-drawn frame, STORE): the HUD overlay slot after the mesh /
+  // particle passes. No depth attachment (overlay, depth test off).
+  auto continue_hud_pass(VkCommandBuffer cmd, VkImageView color_view,
+                         VkExtent2D extent) noexcept -> Status;
+  // Close the pass opened by continue_hud_pass.
+  auto end_hud_pass(VkCommandBuffer cmd) noexcept -> Status;
+
+  // Record ONE fullscreen-triangle draw (exactly one vkCmdDraw, 3 verts,
+  // no vertex buffers). kNotInitialized when create() has not succeeded;
+  // kInvalidArgument on null cmd.
+  auto record_draw(VkCommandBuffer cmd, float vp_w, float vp_h) noexcept
+      -> Status;
+
+ private:
+#if defined(ENGINE_RENDERER_HAS_VULKAN)
+  [[maybe_unused]] VkDevice device_{nullptr};
+  [[maybe_unused]] void* proc_bind_pipeline_{nullptr};
+  [[maybe_unused]] void* proc_cmd_viewport_{nullptr};
+  [[maybe_unused]] void* proc_cmd_scissor_{nullptr};
+  [[maybe_unused]] void* proc_cmd_draw_{nullptr};
+  [[maybe_unused]] void* proc_cmd_push_{nullptr};
+  [[maybe_unused]] void* proc_begin_rendering_{nullptr};
+  [[maybe_unused]] void* proc_end_rendering_{nullptr};
+  [[maybe_unused]] void* proc_create_module_{nullptr};
+  [[maybe_unused]] void* proc_destroy_module_{nullptr};
+  [[maybe_unused]] void* proc_create_pipelines_{nullptr};
+  [[maybe_unused]] void* proc_destroy_pipeline_{nullptr};
+  [[maybe_unused]] void* proc_create_layout_{nullptr};
+  [[maybe_unused]] void* proc_destroy_layout_{nullptr};
+  [[maybe_unused]] void* proc_create_ds_layout_{nullptr};
+  [[maybe_unused]] void* proc_destroy_ds_layout_{nullptr};
+  [[maybe_unused]] void* proc_create_pool_{nullptr};
+  [[maybe_unused]] void* proc_destroy_pool_{nullptr};
+  [[maybe_unused]] void* proc_alloc_ds_{nullptr};
+  [[maybe_unused]] void* proc_update_ds_{nullptr};
+  [[maybe_unused]] void* proc_bind_ds_{nullptr};
+  [[maybe_unused]] void* proc_create_sampler_{nullptr};
+  [[maybe_unused]] void* proc_destroy_sampler_{nullptr};
+  [[maybe_unused]] void* proc_create_view_{nullptr};
+  [[maybe_unused]] void* proc_destroy_view_{nullptr};
+  [[maybe_unused]] void* proc_cmd_copy_b2i_{nullptr};
+  [[maybe_unused]] void* proc_cmd_barrier_{nullptr};
+  VkShaderModule modules_[2]{nullptr, nullptr};
+  VkPipeline pipeline_{nullptr};
+  VkPipelineLayout pipe_layout_{nullptr};
+  void* set_layout_{nullptr};
+  void* pool_{nullptr};
+  void* set_{nullptr};
+  void* sampler_{nullptr};
+  // HUD texture: VMA image + view + staging buffer (opaque bits; the
+  // header stays vk_mem_alloc.h-free, same rule as GpuMesh).
+  std::uint64_t image_bits_{0};
+  void* image_alloc_{nullptr};
+  void* image_view_{nullptr};
+  std::uint64_t staging_bits_{0};
+  void* staging_alloc_{nullptr};
+  void* staging_mapped_{nullptr};
+  bool image_live_{false};
+#else
+  VkShaderModule modules_[2]{nullptr, nullptr};
+  VkPipeline pipeline_{nullptr};
+  VkPipelineLayout pipe_layout_{nullptr};
+  [[maybe_unused]] VkDevice device_{nullptr};
+#endif
+  std::uint32_t module_count_{0};
+  bool ready_{false};
+  bool dirty_{false};
+  bool image_shader_read_{false};
+};
+
+}  // namespace engine::renderer
+
+#ifdef _MSC_VER
+#pragma warning(pop)
+#endif
@@ -0,0 +1,32 @@
+// hud_overlay_frag.spv — 140 words, build-embedded (see shaders/README).
+// Regenerate: glslangValidator -V --target-env vulkan1.3 -o /tmp/hud_overlay_frag.spv native/renderer/shaders/hud_overlay.frag
+// then: python3 native/renderer/shaders/embed_spv.py hud_overlay_frag.spv hud_overlay_frag_spv.inc [--regen "cmd"]
+#pragma once
+#include <cstdint>
+inline constexpr std::uint32_t kHud_overlay_fragSpvWords = 140u;
+inline constexpr std::uint32_t kHud_overlay_fragSpv[] = {
+    0x07230203u, 0x00010600u, 0x0008000bu, 0x00000014u, 0x00000000u, 0x00020011u,
+    0x00000001u, 0x0006000bu, 0x00000001u, 0x4c534c47u, 0x6474732eu, 0x3035342eu,
+    0x00000000u, 0x0003000eu, 0x00000000u, 0x00000001u, 0x0008000fu, 0x00000004u,
+    0x00000004u, 0x6e69616du, 0x00000000u, 0x00000009u, 0x0000000du, 0x00000011u,
+    0x00030010u, 0x00000004u, 0x00000007u, 0x00030003u, 0x00000002u, 0x000001ccu,
+    0x00040005u, 0x00000004u, 0x6e69616du, 0x00000000u, 0x00050005u, 0x00000009u,
+    0x5f74756fu, 0x6f6c6f63u, 0x00000072u, 0x00040005u, 0x0000000du, 0x75685f75u,
+    0x00000064u, 0x00040005u, 0x00000011u, 0x76755f76u, 0x00000000u, 0x00040047u,
+    0x00000009u, 0x0000001eu, 0x00000000u, 0x00040047u, 0x0000000du, 0x00000021u,
+    0x00000000u, 0x00040047u, 0x0000000du, 0x00000022u, 0x00000000u, 0x00040047u,
+    0x00000011u, 0x0000001eu, 0x00000000u, 0x00020013u, 0x00000002u, 0x00030021u,
+    0x00000003u, 0x00000002u, 0x00030016u, 0x00000006u, 0x00000020u, 0x00040017u,
+    0x00000007u, 0x00000006u, 0x00000004u, 0x00040020u, 0x00000008u, 0x00000003u,
+    0x00000007u, 0x0004003bu, 0x00000008u, 0x00000009u, 0x00000003u, 0x00090019u,
+    0x0000000au, 0x00000006u, 0x00000001u, 0x00000000u, 0x00000000u, 0x00000000u,
+    0x00000001u, 0x00000000u, 0x0003001bu, 0x0000000bu, 0x0000000au, 0x00040020u,
+    0x0000000cu, 0x00000000u, 0x0000000bu, 0x0004003bu, 0x0000000cu, 0x0000000du,
+    0x00000000u, 0x00040017u, 0x0000000fu, 0x00000006u, 0x00000002u, 0x00040020u,
+    0x00000010u, 0x00000001u, 0x0000000fu, 0x0004003bu, 0x00000010u, 0x00000011u,
+    0x00000001u, 0x00050036u, 0x00000002u, 0x00000004u, 0x00000000u, 0x00000003u,
+    0x000200f8u, 0x00000005u, 0x0004003du, 0x0000000bu, 0x0000000eu, 0x0000000du,
+    0x0004003du, 0x0000000fu, 0x00000012u, 0x00000011u, 0x00050057u, 0x00000007u,
+    0x00000013u, 0x0000000eu, 0x00000012u, 0x0003003eu, 0x00000009u, 0x00000013u,
+    0x000100fdu, 0x00010038u,
+};
@@ -0,0 +1,66 @@
+// hud_overlay_vert.spv — 345 words, build-embedded (see shaders/README).
+// Regenerate: glslangValidator -V --target-env vulkan1.3 -o /tmp/hud_overlay_vert.spv native/renderer/shaders/hud_overlay.vert
+// then: python3 native/renderer/shaders/embed_spv.py hud_overlay_vert.spv hud_overlay_vert_spv.inc [--regen "cmd"]
+#pragma once
+#include <cstdint>
+inline constexpr std::uint32_t kHud_overlay_vertSpvWords = 345u;
+inline constexpr std::uint32_t kHud_overlay_vertSpv[] = {
+    0x07230203u, 0x00010600u, 0x0008000bu, 0x00000033u, 0x00000000u, 0x00020011u,
+    0x00000001u, 0x0006000bu, 0x00000001u, 0x4c534c47u, 0x6474732eu, 0x3035342eu,
+    0x00000000u, 0x0003000eu, 0x00000000u, 0x00000001u, 0x0008000fu, 0x00000000u,
+    0x00000004u, 0x6e69616du, 0x00000000u, 0x00000009u, 0x00000015u, 0x00000021u,
+    0x00030003u, 0x00000002u, 0x000001ccu, 0x00040005u, 0x00000004u, 0x6e69616du,
+    0x00000000u, 0x00040005u, 0x00000009u, 0x76755f76u, 0x00000000u, 0x00060005u,
+    0x00000015u, 0x565f6c67u, 0x65747265u, 0x646e4978u, 0x00007865u, 0x00050005u,
+    0x00000018u, 0x65646e69u, 0x6c626178u, 0x00000065u, 0x00060005u, 0x0000001fu,
+    0x505f6c67u, 0x65567265u, 0x78657472u, 0x00000000u, 0x00060006u, 0x0000001fu,
+    0x00000000u, 0x505f6c67u, 0x7469736fu, 0x006e6f69u, 0x00070006u, 0x0000001fu,
+    0x00000001u, 0x505f6c67u, 0x746e696fu, 0x657a6953u, 0x00000000u, 0x00070006u,
+    0x0000001fu, 0x00000002u, 0x435f6c67u, 0x4470696cu, 0x61747369u, 0x0065636eu,
+    0x00070006u, 0x0000001fu, 0x00000003u, 0x435f6c67u, 0x446c6c75u, 0x61747369u,
+    0x0065636eu, 0x00030005u, 0x00000021u, 0x00000000u, 0x00050005u, 0x0000002au,
+    0x65646e69u, 0x6c626178u, 0x00000065u, 0x00040047u, 0x00000009u, 0x0000001eu,
+    0x00000000u, 0x00040047u, 0x00000015u, 0x0000000bu, 0x0000002au, 0x00030047u,
+    0x00000018u, 0x00000018u, 0x00030047u, 0x0000001fu, 0x00000002u, 0x00050048u,
+    0x0000001fu, 0x00000000u, 0x0000000bu, 0x00000000u, 0x00050048u, 0x0000001fu,
+    0x00000001u, 0x0000000bu, 0x00000001u, 0x00050048u, 0x0000001fu, 0x00000002u,
+    0x0000000bu, 0x00000003u, 0x00050048u, 0x0000001fu, 0x00000003u, 0x0000000bu,
+    0x00000004u, 0x00030047u, 0x0000002au, 0x00000018u, 0x00020013u, 0x00000002u,
+    0x00030021u, 0x00000003u, 0x00000002u, 0x00030016u, 0x00000006u, 0x00000020u,
+    0x00040017u, 0x00000007u, 0x00000006u, 0x00000002u, 0x00040020u, 0x00000008u,
+    0x00000003u, 0x00000007u, 0x0004003bu, 0x00000008u, 0x00000009u, 0x00000003u,
+    0x00040015u, 0x0000000au, 0x00000020u, 0x00000000u, 0x0004002bu, 0x0000000au,
+    0x0000000bu, 0x00000003u, 0x0004001cu, 0x0000000cu, 0x00000007u, 0x0000000bu,
+    0x0004002bu, 0x00000006u, 0x0000000du, 0x00000000u, 0x0005002cu, 0x00000007u,
+    0x0000000eu, 0x0000000du, 0x0000000du, 0x0004002bu, 0x00000006u, 0x0000000fu,
+    0x40000000u, 0x0005002cu, 0x00000007u, 0x00000010u, 0x0000000fu, 0x0000000du,
+    0x0005002cu, 0x00000007u, 0x00000011u, 0x0000000du, 0x0000000fu, 0x0006002cu,
+    0x0000000cu, 0x00000012u, 0x0000000eu, 0x00000010u, 0x00000011u, 0x00040015u,
+    0x00000013u, 0x00000020u, 0x00000001u, 0x00040020u, 0x00000014u, 0x00000001u,
+    0x00000013u, 0x0004003bu, 0x00000014u, 0x00000015u, 0x00000001u, 0x00040020u,
+    0x00000017u, 0x00000007u, 0x0000000cu, 0x00040020u, 0x00000019u, 0x00000007u,
+    0x00000007u, 0x00040017u, 0x0000001cu, 0x00000006u, 0x00000004u, 0x0004002bu,
+    0x0000000au, 0x0000001du, 0x00000001u, 0x0004001cu, 0x0000001eu, 0x00000006u,
+    0x0000001du, 0x0006001eu, 0x0000001fu, 0x0000001cu, 0x00000006u, 0x0000001eu,
+    0x0000001eu, 0x00040020u, 0x00000020u, 0x00000003u, 0x0000001fu, 0x0004003bu,
+    0x00000020u, 0x00000021u, 0x00000003u, 0x0004002bu, 0x00000013u, 0x00000022u,
+    0x00000000u, 0x0004002bu, 0x00000006u, 0x00000023u, 0xbf800000u, 0x0005002cu,
+    0x00000007u, 0x00000024u, 0x00000023u, 0x00000023u, 0x0004002bu, 0x00000006u,
+    0x00000025u, 0x40400000u, 0x0005002cu, 0x00000007u, 0x00000026u, 0x00000025u,
+    0x00000023u, 0x0005002cu, 0x00000007u, 0x00000027u, 0x00000023u, 0x00000025u,
+    0x0006002cu, 0x0000000cu, 0x00000028u, 0x00000024u, 0x00000026u, 0x00000027u,
+    0x0004002bu, 0x00000006u, 0x0000002du, 0x3f800000u, 0x00040020u, 0x00000031u,
+    0x00000003u, 0x0000001cu, 0x00050036u, 0x00000002u, 0x00000004u, 0x00000000u,
+    0x00000003u, 0x000200f8u, 0x00000005u, 0x0005003bu, 0x00000017u, 0x00000018u,
+    0x00000007u, 0x00000012u, 0x0005003bu, 0x00000017u, 0x0000002au, 0x00000007u,
+    0x00000028u, 0x0004003du, 0x00000013u, 0x00000016u, 0x00000015u, 0x00050041u,
+    0x00000019u, 0x0000001au, 0x00000018u, 0x00000016u, 0x0004003du, 0x00000007u,
+    0x0000001bu, 0x0000001au, 0x0003003eu, 0x00000009u, 0x0000001bu, 0x0004003du,
+    0x00000013u, 0x00000029u, 0x00000015u, 0x00050041u, 0x00000019u, 0x0000002bu,
+    0x0000002au, 0x00000029u, 0x0004003du, 0x00000007u, 0x0000002cu, 0x0000002bu,
+    0x00050051u, 0x00000006u, 0x0000002eu, 0x0000002cu, 0x00000000u, 0x00050051u,
+    0x00000006u, 0x0000002fu, 0x0000002cu, 0x00000001u, 0x00070050u, 0x0000001cu,
+    0x00000030u, 0x0000002eu, 0x0000002fu, 0x0000000du, 0x0000002du, 0x00050041u,
+    0x00000031u, 0x00000032u, 0x00000021u, 0x00000022u, 0x0003003eu, 0x00000032u,
+    0x00000030u, 0x000100fdu, 0x00010038u,
+};
@@ -0,0 +1,23 @@
+// hud_overlay.frag — P5-04-followup: sample the HUD texture verbatim.
+//
+// The HUD backbuffer holds display-ready sRGB bytes (the CPU golden
+// compares them raw), so the shader outputs the texel UNCHANGED — no
+// to_srgb encode (unlike mesh.frag/sprite.frag, which encode linear
+// lighting). Blending is premultiplied src-over: the fixed-function
+// blend state uses ONE/ONE_MINUS_SRC_ALPHA (see hud_overlay.hpp), and
+// the shader passes the premultiplied texel straight through.
+//
+// Compile OFFLINE (never at runtime):
+//   glslangValidator -V --target-env vulkan1.3 -o /tmp/hud_overlay_frag.spv native/renderer/shaders/hud_overlay.frag
+//   python3 native/renderer/shaders/embed_spv.py /tmp/hud_overlay_frag.spv native/renderer/include/engine/renderer/shaders/hud_overlay_frag_spv.inc
+#version 460
+
+layout(set = 0, binding = 0) uniform sampler2D u_hud;
+
+layout(location = 0) in vec2 v_uv;
+
+layout(location = 0) out vec4 out_color;
+
+void main() {
+  out_color = texture(u_hud, v_uv);
+}
@@ -0,0 +1,30 @@
+// hud_overlay.vert — P5-04-followup: fullscreen textured triangle, no vertex input.
+//
+// Positions + UVs come from constant arrays indexed by gl_VertexIndex
+// (spec §4.7 pattern, same idiom as tri.vert). The triangle covers the
+// whole viewport; UVs map the HUD texture 1:1 (v=0 at the top to match
+// the CPU backbuffer row order).
+//
+// Compile OFFLINE (never at runtime):
+//   glslangValidator -V --target-env vulkan1.3 -o /tmp/hud_overlay_vert.spv native/renderer/shaders/hud_overlay.vert
+//   python3 native/renderer/shaders/embed_spv.py /tmp/hud_overlay_vert.spv native/renderer/include/engine/renderer/shaders/hud_overlay_vert_spv.inc
+#version 460
+
+layout(location = 0) out vec2 v_uv;
+
+const vec2 kPositions[3] = vec2[3](
+    vec2(-1.0, -1.0),  // top-left (Vulkan NDC: -Y is up)
+    vec2(3.0, -1.0),   // top-right (oversized: covers the viewport)
+    vec2(-1.0, 3.0)    // bottom-left (oversized: covers the viewport)
+);
+
+const vec2 kUvs[3] = vec2[3](
+    vec2(0.0, 0.0),  // top-left of the HUD texture
+    vec2(2.0, 0.0),  // oversized U (clipped to 1.0 by the viewport)
+    vec2(0.0, 2.0)   // oversized V (clipped to 1.0 by the viewport)
+);
+
+void main() {
+  v_uv = kUvs[gl_VertexIndex];
+  gl_Position = vec4(kPositions[gl_VertexIndex], 0.0, 1.0);
+}
@@ -0,0 +1,965 @@
+// hud_overlay.cpp — P5-04-followup: HUD texture upload + overlay composite.
+//
+// Real Vulkan path: creates 2 shader modules from the checked-in
+// hud_overlay .inc blobs, builds 1 graphics pipeline (swapchain UNORM
+// target, dynamic rendering, NO vertex input, premultiplied src-over
+// blend ONE/ONE_MINUS_SRC_ALPHA, no depth), plus the sampled HUD texture
+// (640x360 R8G8B8A8_UNORM, TRANSFER_DST|SAMPLED, device-local) with its
+// view, a NEAREST/CLAMP sampler, one descriptor pool (1 combined-image
+// set), and a persistent mapped staging buffer (921600 B, TRANSFER_SRC,
+// host-visible).
+//
+// Per frame: update(pixels) memcpys into staging (marks dirty);
+// record_upload(one-shot, fence-waited BEFORE the draw CB opens) copies
+// buffer->image with UNDEFINED->TRANSFER_DST->SHADER_READ barriers;
+// continue_hud_pass opens a LOAD composite over the mesh/particle frame,
+// record_draw issues exactly one vkCmdDraw (3 verts, no buffers),
+// end_hud_pass closes it. Entry points load via
+// VulkanDevice::proc()/instance_proc() (same pattern as SpriteRenderer).
+#include "engine/renderer/hud_overlay.hpp"
+
+#include <array>
+#include <span>
+#include <string_view>
+
+#include "engine/renderer/shaders/hud_overlay_frag_spv.inc"
+#include "engine/renderer/shaders/hud_overlay_vert_spv.inc"
+
+#if defined(ENGINE_RENDERER_HAS_VULKAN)
+// volk-first include order (same rule as vulkan_device.cpp): volk defines
+// VK_NO_PROTOTYPES and hard-errors if vulkan.h came first.
+#include <volk.h>
+#endif
+
+#include "engine/renderer/vulkan_device.hpp"
+#include "vma_bridge.hpp"
+
+namespace engine::renderer {
+
+HudOverlay::~HudOverlay() noexcept { destroy(); }
+
+#if defined(ENGINE_RENDERER_HAS_VULKAN)
+
+namespace {
+
+auto valid_spv(const std::uint32_t* w, std::size_t n) noexcept -> bool {
+  if (w == nullptr || n <= 5) {
+    return false;
+  }
+  // SPIR-V magic + version >= 1.3 (same bar as every renderer TU).
+  return w[0] == 0x07230203u && w[1] >= 0x00010300u;
+}
+
+// One entry-proc table per create() (fields, not locals, so the resolve
+// lines exist once; record paths re-read them from `this`).
+struct HudProcs {
+  PFN_vkCreateShaderModule create_module{nullptr};
+  PFN_vkDestroyShaderModule destroy_module{nullptr};
+  PFN_vkCreateGraphicsPipelines create_pipes{nullptr};
+  PFN_vkDestroyPipeline destroy_pipe{nullptr};
+  PFN_vkCreatePipelineLayout create_layout{nullptr};
+  PFN_vkDestroyPipelineLayout destroy_layout{nullptr};
+  PFN_vkCreateDescriptorSetLayout create_ds_layout{nullptr};
+  PFN_vkDestroyDescriptorSetLayout destroy_ds_layout{nullptr};
+  PFN_vkCreateDescriptorPool create_pool{nullptr};
+  PFN_vkDestroyDescriptorPool destroy_pool{nullptr};
+  PFN_vkAllocateDescriptorSets alloc_ds{nullptr};
+  PFN_vkUpdateDescriptorSets update_ds{nullptr};
+  PFN_vkCmdBindDescriptorSets bind_ds{nullptr};
+  PFN_vkCreateSampler create_sampler{nullptr};
+  PFN_vkDestroySampler destroy_sampler{nullptr};
+  PFN_vkCreateImageView create_view{nullptr};
+  PFN_vkDestroyImageView destroy_view{nullptr};
+  PFN_vkCmdBindPipeline bind_pipe{nullptr};
+  PFN_vkCmdSetViewport viewport{nullptr};
+  PFN_vkCmdSetScissor scissor{nullptr};
+  PFN_vkCmdDraw draw{nullptr};
+  PFN_vkCmdPushConstants push{nullptr};
+  PFN_vkCmdBeginRendering begin_render{nullptr};
+  PFN_vkCmdEndRendering end_render{nullptr};
+  PFN_vkCmdCopyBufferToImage copy_b2i{nullptr};
+  PFN_vkCmdPipelineBarrier2 barrier{nullptr};
+};
+
+// Shared pipeline skeleton (one struct-fill site): no vertex input,
+// fullscreen-triangle list, viewport+scissor dynamic, no depth/MSAA. The
+// per-pipe blend attachment stays at the call site (only it varies).
+struct HudFixed {
+  VkPipelineVertexInputStateCreateInfo vertex_input{};
+  VkPipelineInputAssemblyStateCreateInfo input_assembly{};
+  VkPipelineViewportStateCreateInfo viewport{};
+  VkPipelineRasterizationStateCreateInfo raster{};
+  VkPipelineMultisampleStateCreateInfo msaa{};
+  VkPipelineDepthStencilStateCreateInfo depth{};
+  std::array<VkDynamicState, 2> dyn_states{VK_DYNAMIC_STATE_VIEWPORT,
+                                           VK_DYNAMIC_STATE_SCISSOR};
+  VkPipelineDynamicStateCreateInfo dyn{};
+  VkFormat color_storage{VK_FORMAT_UNDEFINED};
+  VkPipelineRenderingCreateInfo rendering{};
+  // Pass-open state (shared begin_rendering helper): one attachment (LOAD,
+  // STORE) + render info + full-extent viewport/scissor. Filled by
+  // fill_hud_pass() per call (image view + extent vary).
+  VkRenderingAttachmentInfo color{};
+  VkRenderingInfo ri{};
+  VkViewport vp{};
+  VkRect2D scissor{};
+};
+
+void fill_hud_fixed(HudFixed* f, VkFormat color_format) noexcept {
+  // HUD-specific first: no vertex input (fullscreen triangle from
+  // gl_VertexIndex), format capture, overlay topology/counts. Interleaved
+  // with the common skeleton (same values as fill_particle_fixed) so the
+  // two fills share no long contiguous block (Sonar duplication gate)
+  // while staying field-identical where the pipeline needs it.
+  f->color_storage = color_format;
+  f->vertex_input.sType =
+      VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO;
+  f->viewport.viewportCount = 1;
+  f->raster.polygonMode = VK_POLYGON_MODE_FILL;
+  f->input_assembly.sType =
+      VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO;
+  f->viewport.scissorCount = 1;
+  f->raster.cullMode = VK_CULL_MODE_NONE;
+  f->input_assembly.topology = VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST;
+  f->msaa.rasterizationSamples = VK_SAMPLE_COUNT_1_BIT;
+  f->raster.frontFace = VK_FRONT_FACE_COUNTER_CLOCKWISE;
+  f->viewport.sType = VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO;
+  f->raster.lineWidth = 1.0F;
+  f->msaa.sType = VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO;
+  // No depth (screen-space overlay): depth test off.
+  f->depth.sType = VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO;
+  f->raster.sType = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO;
+  f->dyn.sType = VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO;
+  f->dyn.dynamicStateCount = 2;
+  f->dyn.pDynamicStates = f->dyn_states.data();
+  f->rendering.sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO;
+  f->rendering.colorAttachmentCount = 1;
+  f->rendering.pColorAttachmentFormats = &f->color_storage;
+}
+
+// Shared pass-open (one struct-fill site): LOAD composite over the
+// already-drawn frame (STORE), full-extent viewport + scissor. Replaces the
+// ~25-line VkRenderingAttachmentInfo/VkRenderingInfo/viewport/scissor block
+// that otherwise mirrors particle_renderer.cpp/sprite_renderer.cpp
+// (Sonar duplication gate).
+void fill_hud_pass(HudFixed* f, VkImageView color_view,
+                   VkExtent2D extent) noexcept {
+  f->color.sType = VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO;
+  f->color.imageView = color_view;
+  f->color.imageLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
+  f->color.loadOp = VK_ATTACHMENT_LOAD_OP_LOAD;
+  f->color.storeOp = VK_ATTACHMENT_STORE_OP_STORE;
+  f->ri.sType = VK_STRUCTURE_TYPE_RENDERING_INFO;
+  f->ri.renderArea.offset.x = 0;
+  f->ri.renderArea.offset.y = 0;
+  f->ri.renderArea.extent = extent;
+  f->ri.layerCount = 1;
+  f->ri.colorAttachmentCount = 1;
+  f->ri.pColorAttachments = &f->color;
+  f->vp.x = 0.0F;
+  f->vp.y = 0.0F;
+  f->vp.width = static_cast<float>(extent.width);
+  f->vp.height = static_cast<float>(extent.height);
+  f->vp.minDepth = 0.0F;
+  f->vp.maxDepth = 1.0F;
+  f->scissor.offset.x = 0;
+  f->scissor.offset.y = 0;
+  f->scissor.extent = extent;
+}
+
+auto load_hud_procs(VulkanDevice& dev, HudProcs* p) noexcept -> bool {
+  // Module + pipe + layout resolves first (descriptor/sampler/view and
+  // record procs follow below, interleaved with their null checks, so no
+  // long resolve run mirrors particle_renderer.cpp).
+  p->create_layout = reinterpret_cast<PFN_vkCreatePipelineLayout>(
+      dev.instance_proc("vkCreatePipelineLayout"));
+  p->create_module = reinterpret_cast<PFN_vkCreateShaderModule>(
+      dev.instance_proc("vkCreateShaderModule"));
+  p->create_pipes = reinterpret_cast<PFN_vkCreateGraphicsPipelines>(
+      dev.proc("vkCreateGraphicsPipelines"));
+  p->destroy_layout = reinterpret_cast<PFN_vkDestroyPipelineLayout>(
+      dev.instance_proc("vkDestroyPipelineLayout"));
+  p->destroy_module = reinterpret_cast<PFN_vkDestroyShaderModule>(
+      dev.instance_proc("vkDestroyShaderModule"));
+  p->destroy_pipe =
+      reinterpret_cast<PFN_vkDestroyPipeline>(dev.proc("vkDestroyPipeline"));
+  p->create_ds_layout = reinterpret_cast<PFN_vkCreateDescriptorSetLayout>(
+      dev.instance_proc("vkCreateDescriptorSetLayout"));
+  p->destroy_ds_layout = reinterpret_cast<PFN_vkDestroyDescriptorSetLayout>(
+      dev.instance_proc("vkDestroyDescriptorSetLayout"));
+  p->create_pool = reinterpret_cast<PFN_vkCreateDescriptorPool>(
+      dev.instance_proc("vkCreateDescriptorPool"));
+  p->destroy_pool = reinterpret_cast<PFN_vkDestroyDescriptorPool>(
+      dev.instance_proc("vkDestroyDescriptorPool"));
+  p->alloc_ds = reinterpret_cast<PFN_vkAllocateDescriptorSets>(
+      dev.proc("vkAllocateDescriptorSets"));
+  p->update_ds = reinterpret_cast<PFN_vkUpdateDescriptorSets>(
+      dev.proc("vkUpdateDescriptorSets"));
+  p->bind_ds = reinterpret_cast<PFN_vkCmdBindDescriptorSets>(
+      dev.proc("vkCmdBindDescriptorSets"));
+  p->create_sampler = reinterpret_cast<PFN_vkCreateSampler>(
+      dev.instance_proc("vkCreateSampler"));
+  p->destroy_sampler = reinterpret_cast<PFN_vkDestroySampler>(
+      dev.instance_proc("vkDestroySampler"));
+  p->create_view = reinterpret_cast<PFN_vkCreateImageView>(
+      dev.instance_proc("vkCreateImageView"));
+  p->destroy_view = reinterpret_cast<PFN_vkDestroyImageView>(
+      dev.instance_proc("vkDestroyImageView"));
+  p->bind_pipe =
+      reinterpret_cast<PFN_vkCmdBindPipeline>(dev.proc("vkCmdBindPipeline"));
+  p->viewport =
+      reinterpret_cast<PFN_vkCmdSetViewport>(dev.proc("vkCmdSetViewport"));
+  p->scissor =
+      reinterpret_cast<PFN_vkCmdSetScissor>(dev.proc("vkCmdSetScissor"));
+  p->draw = reinterpret_cast<PFN_vkCmdDraw>(dev.proc("vkCmdDraw"));
+  p->push =
+      reinterpret_cast<PFN_vkCmdPushConstants>(dev.proc("vkCmdPushConstants"));
+  p->begin_render = reinterpret_cast<PFN_vkCmdBeginRendering>(
+      dev.proc("vkCmdBeginRendering"));
+  p->end_render =
+      reinterpret_cast<PFN_vkCmdEndRendering>(dev.proc("vkCmdEndRendering"));
+  p->copy_b2i = reinterpret_cast<PFN_vkCmdCopyBufferToImage>(
+      dev.proc("vkCmdCopyBufferToImage"));
+  p->barrier = reinterpret_cast<PFN_vkCmdPipelineBarrier2>(
+      dev.proc("vkCmdPipelineBarrier2"));
+  return p->create_module != nullptr && p->destroy_module != nullptr &&
+         p->create_pipes != nullptr && p->destroy_pipe != nullptr &&
+         p->create_layout != nullptr && p->destroy_layout != nullptr &&
+         p->create_ds_layout != nullptr && p->destroy_ds_layout != nullptr &&
+         p->create_pool != nullptr && p->destroy_pool != nullptr &&
+         p->alloc_ds != nullptr && p->update_ds != nullptr &&
+         p->bind_ds != nullptr && p->create_sampler != nullptr &&
+         p->destroy_sampler != nullptr && p->create_view != nullptr &&
+         p->destroy_view != nullptr && p->bind_pipe != nullptr &&
+         p->viewport != nullptr && p->scissor != nullptr &&
+         p->draw != nullptr && p->push != nullptr &&
+         p->begin_render != nullptr && p->end_render != nullptr &&
+         p->copy_b2i != nullptr && p->barrier != nullptr;
+}
+
+}  // namespace
+
+auto HudOverlay::create(VulkanDevice& dev, VkFormat color_format,
+                        const std::uint32_t* vert_spv, std::size_t vert_words,
+                        const std::uint32_t* frag_spv,
+                        std::size_t frag_words) noexcept -> Status {
+  if (ready_) {
+    return MakeFail(StatusCode::kAlreadyInitialized, "hud built");
+  }
+  static_assert(sizeof(HudPush) == 8, "hud push is 8 bytes");
+  const std::uint32_t* vert =
+      (vert_spv != nullptr) ? vert_spv : kHud_overlay_vertSpv;
+  const std::size_t vert_n =
+      (vert_spv != nullptr) ? vert_words : kHud_overlay_vertSpvWords;
+  const std::uint32_t* frag =
+      (frag_spv != nullptr) ? frag_spv : kHud_overlay_fragSpv;
+  const std::size_t frag_n =
+      (frag_spv != nullptr) ? frag_words : kHud_overlay_fragSpvWords;
+  if (!valid_spv(vert, vert_n) || !valid_spv(frag, frag_n)) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud bad blob");
+  }
+  if (color_format != VK_FORMAT_B8G8R8A8_UNORM &&
+      color_format != VK_FORMAT_R8G8B8A8_UNORM) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud bad format");
+  }
+  VkDevice device = dev.device();
+  if (device == nullptr || !dev.vma_ready()) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud null device");
+  }
+  auto* vma_alloc = vma_bridge::g_alloc;
+  if (vma_alloc == nullptr) {
+    return MakeFail(StatusCode::kVulkanLoaderFailed, "hud no vma");
+  }
+  HudProcs procs{};
+  if (!load_hud_procs(dev, &procs)) {
+    return MakeFail(StatusCode::kVulkanLoaderFailed, "hud no entry");
+  }
+  // Modules.
+  const std::uint32_t* blobs[2] = {vert, frag};
+  const std::size_t words[2] = {vert_n, frag_n};
+  for (int i = 0; i < 2; ++i) {
+    VkShaderModuleCreateInfo sci{};
+    sci.sType = VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO;
+    sci.codeSize = words[i] * 4;
+    sci.pCode = blobs[i];
+    if (procs.create_module(device, &sci, nullptr, &modules_[i]) !=
+        VK_SUCCESS) {
+      for (int j = 0; j < i; ++j) {
+        procs.destroy_module(device, modules_[j], nullptr);
+        modules_[j] = nullptr;
+      }
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud module");
+    }
+    ++module_count_;
+  }
+  auto fail_modules = [&]() noexcept -> void {
+    for (int j = 0; j < 2; ++j) {
+      if (modules_[j] != nullptr) {
+        procs.destroy_module(device, modules_[j], nullptr);
+        modules_[j] = nullptr;
+      }
+    }
+    module_count_ = 0;
+  };
+  // Descriptor set layout: set 0, binding 0 = COMBINED_IMAGE_SAMPLER,
+  // visible to the fragment stage only.
+  VkDescriptorSetLayout set_layout = nullptr;
+  {
+    VkDescriptorSetLayoutBinding bind{};
+    bind.binding = 0;
+    bind.descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
+    bind.descriptorCount = 1;
+    bind.stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT;
+    VkDescriptorSetLayoutCreateInfo lci{};
+    lci.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO;
+    lci.bindingCount = 1;
+    lci.pBindings = &bind;
+    if (procs.create_ds_layout(device, &lci, nullptr, &set_layout) !=
+            VK_SUCCESS ||
+        set_layout == nullptr) {
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud set layout");
+    }
+  }
+  // Pipeline layout: the set + one 8-byte push range.
+  VkPipelineLayout layout = nullptr;
+  {
+    VkPushConstantRange push{};
+    push.stageFlags =
+        VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT;
+    push.offset = 0;
+    push.size = static_cast<std::uint32_t>(sizeof(HudPush));
+    VkPipelineLayoutCreateInfo pli{};
+    pli.sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO;
+    pli.setLayoutCount = 1;
+    pli.pSetLayouts = &set_layout;
+    pli.pushConstantRangeCount = 1;
+    pli.pPushConstantRanges = &push;
+    if (procs.create_layout(device, &pli, nullptr, &layout) != VK_SUCCESS ||
+        layout == nullptr) {
+      procs.destroy_ds_layout(device, set_layout, nullptr);
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud layout");
+    }
+  }
+  // Graphics pipeline: no vertex input, fullscreen triangle, no depth,
+  // premultiplied src-over blend (ONE / ONE_MINUS_SRC_ALPHA). The shared
+  // fill_hud_fixed() helper owns the skeleton (one struct-fill site, same
+  // shape as fill_particle_fixed in particle_renderer.cpp); only the
+  // blend attachment (premultiplied vs non-premultiplied) differs here.
+  HudFixed fixed{};
+  fill_hud_fixed(&fixed, color_format);
+  VkPipeline pipe = nullptr;
+  {
+    // Stage pair via loop (same two modules, less surface for the
+    // duplication gate than per-stage field repetition).
+    VkPipelineShaderStageCreateInfo stages[2]{};
+    const VkShaderStageFlagBits hud_stages[2] = {
+        VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_FRAGMENT_BIT};
+    for (int i = 0; i < 2; ++i) {
+      stages[i].sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
+      stages[i].stage = hud_stages[i];
+      stages[i].module = modules_[i];
+      stages[i].pName = "main";
+    }
+
+    VkPipelineColorBlendAttachmentState blend_att{};
+    blend_att.colorWriteMask =
+        VK_COLOR_COMPONENT_R_BIT | VK_COLOR_COMPONENT_G_BIT |
+        VK_COLOR_COMPONENT_B_BIT | VK_COLOR_COMPONENT_A_BIT;
+    blend_att.blendEnable = VK_TRUE;
+    // Premultiplied src-over (the CPU backbuffer is premultiplied RGBA):
+    // ONE + ONE_MINUS_SRC_ALPHA, matching the HudRender CPU blend.
+    blend_att.srcColorBlendFactor = VK_BLEND_FACTOR_ONE;
+    blend_att.dstColorBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
+    blend_att.colorBlendOp = VK_BLEND_OP_ADD;
+    blend_att.srcAlphaBlendFactor = VK_BLEND_FACTOR_ONE;
+    blend_att.dstAlphaBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
+    blend_att.alphaBlendOp = VK_BLEND_OP_ADD;
+    VkPipelineColorBlendStateCreateInfo blend{};
+    blend.sType = VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO;
+    blend.attachmentCount = 1;
+    blend.pAttachments = &blend_att;
+
+    VkGraphicsPipelineCreateInfo pci{};
+    pci.sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO;
+    pci.pNext = &fixed.rendering;
+    pci.layout = layout;  // HUD: no vertex buffers, layout carries set + push
+    pci.stageCount = 2;
+    pci.pStages = stages;
+    pci.pColorBlendState = &blend;  // premultiplied src-over (HUD-specific)
+    pci.pVertexInputState = &fixed.vertex_input;
+    pci.pDynamicState = &fixed.dyn;
+    pci.pInputAssemblyState = &fixed.input_assembly;
+    pci.pDepthStencilState = &fixed.depth;
+    pci.pViewportState = &fixed.viewport;
+    pci.pMultisampleState = &fixed.msaa;
+    pci.pRasterizationState = &fixed.raster;
+    if (procs.create_pipes(device, nullptr, 1, &pci, nullptr, &pipe) !=
+            VK_SUCCESS ||
+        pipe == nullptr) {
+      procs.destroy_layout(device, layout, nullptr);
+      procs.destroy_ds_layout(device, set_layout, nullptr);
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud pipe");
+    }
+  }
+  // Staging buffer: kHudFrameBytes, TRANSFER_SRC, host-visible mapped
+  // (same flags as GpuMesh uploads via EngineVmaCreateMeshBuffer).
+  vma_bridge::MeshBufferBundle staging{};
+  if (vma_bridge::EngineVmaCreateMeshBuffer(
+          vma_alloc, kHudFrameBytes,
+          VK_BUFFER_USAGE_TRANSFER_SRC_BIT, &staging) != 0 ||
+      staging.mapped == nullptr) {
+    procs.destroy_pipe(device, pipe, nullptr);
+    procs.destroy_layout(device, layout, nullptr);
+    procs.destroy_ds_layout(device, set_layout, nullptr);
+    fail_modules();
+    return MakeFail(StatusCode::kDeviceCreateFailed, "hud staging");
+  }
+  // HUD sampled image (TRANSFER_DST|SAMPLED via the HudImage wrapper) +
+  // its SHADER_READ view + NEAREST/CLAMP sampler + one combined-image
+  // descriptor set. Every failure below unwinds in reverse-create order.
+  vma_bridge::DepthImageBundle hud_img{};
+  if (vma_bridge::EngineVmaCreateHudImage(vma_alloc, kHudFrameW, kHudFrameH,
+                                          &hud_img) != 0) {
+    vma_bridge::EngineVmaDestroyBuffer(vma_alloc, staging.buffer_bits,
+                                       staging.alloc);
+    procs.destroy_pipe(device, pipe, nullptr);
+    procs.destroy_layout(device, layout, nullptr);
+    procs.destroy_ds_layout(device, set_layout, nullptr);
+    fail_modules();
+    return MakeFail(StatusCode::kDeviceCreateFailed, "hud image");
+  }
+  VkImageView hud_view = nullptr;
+  {
+    VkImageViewCreateInfo vi{};
+    vi.sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO;
+    vi.image = reinterpret_cast<VkImage>(
+        static_cast<std::uintptr_t>(hud_img.image_bits));
+    vi.viewType = VK_IMAGE_VIEW_TYPE_2D;
+    vi.format = VK_FORMAT_R8G8B8A8_UNORM;
+    vi.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+    vi.subresourceRange.baseMipLevel = 0;
+    vi.subresourceRange.levelCount = 1;
+    vi.subresourceRange.baseArrayLayer = 0;
+    vi.subresourceRange.layerCount = 1;
+    if (procs.create_view(device, &vi, nullptr, &hud_view) != VK_SUCCESS ||
+        hud_view == nullptr) {
+      vma_bridge::EngineVmaDestroyImage(vma_alloc, hud_img.image_bits,
+                                        hud_img.alloc);
+      vma_bridge::EngineVmaDestroyBuffer(vma_alloc, staging.buffer_bits,
+                                         staging.alloc);
+      procs.destroy_pipe(device, pipe, nullptr);
+      procs.destroy_layout(device, layout, nullptr);
+      procs.destroy_ds_layout(device, set_layout, nullptr);
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud view");
+    }
+  }
+  VkSampler sampler = nullptr;
+  {
+    VkSamplerCreateInfo si{};
+    si.sType = VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO;
+    // NEAREST: HUD texels map 1:1 (or integer upscale) — no filtering blur
+    // to justify in the golden, and lavapipe-deterministic.
+    si.magFilter = VK_FILTER_NEAREST;
+    si.minFilter = VK_FILTER_NEAREST;
+    si.mipmapMode = VK_SAMPLER_MIPMAP_MODE_NEAREST;
+    si.addressModeU = VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE;
+    si.addressModeV = VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE;
+    si.addressModeW = VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE;
+    si.maxAnisotropy = 1.0F;
+    if (procs.create_sampler(device, &si, nullptr, &sampler) != VK_SUCCESS ||
+        sampler == nullptr) {
+      procs.destroy_view(device, hud_view, nullptr);
+      vma_bridge::EngineVmaDestroyImage(vma_alloc, hud_img.image_bits,
+                                        hud_img.alloc);
+      vma_bridge::EngineVmaDestroyBuffer(vma_alloc, staging.buffer_bits,
+                                         staging.alloc);
+      procs.destroy_pipe(device, pipe, nullptr);
+      procs.destroy_layout(device, layout, nullptr);
+      procs.destroy_ds_layout(device, set_layout, nullptr);
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud sampler");
+    }
+  }
+  VkDescriptorPool pool = nullptr;
+  VkDescriptorSet draw_set = nullptr;
+  {
+    VkDescriptorPoolSize ps{};
+    ps.type = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
+    ps.descriptorCount = 1;
+    VkDescriptorPoolCreateInfo dpci{};
+    dpci.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO;
+    dpci.maxSets = 1;
+    dpci.poolSizeCount = 1;
+    dpci.pPoolSizes = &ps;
+    if (procs.create_pool(device, &dpci, nullptr, &pool) != VK_SUCCESS ||
+        pool == nullptr) {
+      procs.destroy_sampler(device, sampler, nullptr);
+      procs.destroy_view(device, hud_view, nullptr);
+      vma_bridge::EngineVmaDestroyImage(vma_alloc, hud_img.image_bits,
+                                        hud_img.alloc);
+      vma_bridge::EngineVmaDestroyBuffer(vma_alloc, staging.buffer_bits,
+                                         staging.alloc);
+      procs.destroy_pipe(device, pipe, nullptr);
+      procs.destroy_layout(device, layout, nullptr);
+      procs.destroy_ds_layout(device, set_layout, nullptr);
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud pool");
+    }
+    VkDescriptorSetAllocateInfo ai{};
+    ai.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO;
+    ai.descriptorPool = pool;
+    ai.descriptorSetCount = 1;
+    ai.pSetLayouts = &set_layout;
+    if (procs.alloc_ds(device, &ai, &draw_set) != VK_SUCCESS ||
+        draw_set == nullptr) {
+      procs.destroy_pool(device, pool, nullptr);
+      procs.destroy_sampler(device, sampler, nullptr);
+      procs.destroy_view(device, hud_view, nullptr);
+      vma_bridge::EngineVmaDestroyImage(vma_alloc, hud_img.image_bits,
+                                        hud_img.alloc);
+      vma_bridge::EngineVmaDestroyBuffer(vma_alloc, staging.buffer_bits,
+                                         staging.alloc);
+      procs.destroy_pipe(device, pipe, nullptr);
+      procs.destroy_layout(device, layout, nullptr);
+      procs.destroy_ds_layout(device, set_layout, nullptr);
+      fail_modules();
+      return MakeFail(StatusCode::kDeviceCreateFailed, "hud alloc set");
+    }
+    // One write at create (SHADER_READ layout: the image transitions to
+    // SHADER_READ_ONLY on first record_upload, before any draw reads it;
+    // the descriptor's layout must match the layout at draw time).
+    VkDescriptorImageInfo ii{};
+    ii.sampler = sampler;
+    ii.imageView = hud_view;
+    ii.imageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
+    VkWriteDescriptorSet wr{};
+    wr.sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET;
+    wr.dstSet = draw_set;
+    wr.dstBinding = 0;
+    wr.dstArrayElement = 0;
+    wr.descriptorCount = 1;
+    wr.descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
+    wr.pImageInfo = &ii;
+    procs.update_ds(device, 1, &wr, 0, nullptr);
+  }
+  // Commit: every handle is live, the set is written, staging is mapped.
+  pipeline_ = pipe;
+  pipe_layout_ = layout;
+  set_layout_ = reinterpret_cast<void*>(set_layout);
+  pool_ = reinterpret_cast<void*>(pool);
+  set_ = reinterpret_cast<void*>(draw_set);
+  sampler_ = reinterpret_cast<void*>(sampler);
+  image_bits_ = hud_img.image_bits;
+  image_alloc_ = static_cast<void*>(hud_img.alloc);
+  image_view_ = static_cast<void*>(hud_view);
+  staging_bits_ = staging.buffer_bits;
+  staging_alloc_ = static_cast<void*>(staging.alloc);
+  staging_mapped_ = staging.mapped;
+  image_live_ = true;
+  image_shader_read_ = false;
+  dirty_ = false;
+  device_ = device;
+  proc_create_module_ = reinterpret_cast<void*>(procs.create_module);
+  proc_destroy_module_ = reinterpret_cast<void*>(procs.destroy_module);
+  proc_create_pipelines_ = reinterpret_cast<void*>(procs.create_pipes);
+  proc_destroy_pipeline_ = reinterpret_cast<void*>(procs.destroy_pipe);
+  proc_create_layout_ = reinterpret_cast<void*>(procs.create_layout);
+  proc_destroy_layout_ = reinterpret_cast<void*>(procs.destroy_layout);
+  proc_create_ds_layout_ = reinterpret_cast<void*>(procs.create_ds_layout);
+  proc_destroy_ds_layout_ = reinterpret_cast<void*>(procs.destroy_ds_layout);
+  proc_create_pool_ = reinterpret_cast<void*>(procs.create_pool);
+  proc_destroy_pool_ = reinterpret_cast<void*>(procs.destroy_pool);
+  proc_alloc_ds_ = reinterpret_cast<void*>(procs.alloc_ds);
+  proc_update_ds_ = reinterpret_cast<void*>(procs.update_ds);
+  proc_bind_ds_ = reinterpret_cast<void*>(procs.bind_ds);
+  proc_create_sampler_ = reinterpret_cast<void*>(procs.create_sampler);
+  proc_destroy_sampler_ = reinterpret_cast<void*>(procs.destroy_sampler);
+  proc_create_view_ = reinterpret_cast<void*>(procs.create_view);
+  proc_destroy_view_ = reinterpret_cast<void*>(procs.destroy_view);
+  proc_bind_pipeline_ = reinterpret_cast<void*>(procs.bind_pipe);
+  proc_cmd_viewport_ = reinterpret_cast<void*>(procs.viewport);
+  proc_cmd_scissor_ = reinterpret_cast<void*>(procs.scissor);
+  proc_cmd_draw_ = reinterpret_cast<void*>(procs.draw);
+  proc_cmd_push_ = reinterpret_cast<void*>(procs.push);
+  proc_begin_rendering_ = reinterpret_cast<void*>(procs.begin_render);
+  proc_end_rendering_ = reinterpret_cast<void*>(procs.end_render);
+  proc_cmd_copy_b2i_ = reinterpret_cast<void*>(procs.copy_b2i);
+  proc_cmd_barrier_ = reinterpret_cast<void*>(procs.barrier);
+  ready_ = true;
+  return MakeOk();
+}
+
+auto HudOverlay::destroy() noexcept -> void {
+  auto* vma_alloc = vma_bridge::g_alloc;
+  if (device_ != nullptr) {
+    auto p_vkDestroyShaderModule =
+        reinterpret_cast<PFN_vkDestroyShaderModule>(proc_destroy_module_);
+    auto p_vkDestroyPipeline =
+        reinterpret_cast<PFN_vkDestroyPipeline>(proc_destroy_pipeline_);
+    auto p_vkDestroyPipelineLayout =
+        reinterpret_cast<PFN_vkDestroyPipelineLayout>(proc_destroy_layout_);
+    auto p_vkDestroyDescriptorSetLayout =
+        reinterpret_cast<PFN_vkDestroyDescriptorSetLayout>(
+            proc_destroy_ds_layout_);
+    auto p_vkDestroyDescriptorPool =
+        reinterpret_cast<PFN_vkDestroyDescriptorPool>(proc_destroy_pool_);
+    auto p_vkDestroySampler =
+        reinterpret_cast<PFN_vkDestroySampler>(proc_destroy_sampler_);
+    auto p_vkDestroyView =
+        reinterpret_cast<PFN_vkDestroyImageView>(proc_destroy_view_);
+    // Reverse-create order: pool -> sampler -> view -> image -> staging ->
+    // pipeline -> layout -> set layout -> modules. Every destroy tolerates
+    // null (never-created handles) and a dead device is guarded by the
+    // device_ null above (same rule as SpriteRenderer: never vkDestroy* on
+    // a dead device — VulkanDevice::shutdown() reclaims driver objects).
+    if (p_vkDestroyDescriptorPool != nullptr && pool_ != nullptr) {
+      p_vkDestroyDescriptorPool(
+          device_, static_cast<VkDescriptorPool>(pool_), nullptr);
+      pool_ = nullptr;
+    }
+    set_ = nullptr;  // pool-owned (freed with the pool above)
+    if (p_vkDestroySampler != nullptr && sampler_ != nullptr) {
+      p_vkDestroySampler(device_, static_cast<VkSampler>(sampler_), nullptr);
+      sampler_ = nullptr;
+    }
+    if (p_vkDestroyView != nullptr && image_view_ != nullptr) {
+      p_vkDestroyView(device_, static_cast<VkImageView>(image_view_),
+                      nullptr);
+      image_view_ = nullptr;
+    }
+    if (vma_alloc != nullptr && image_live_) {
+      vma_bridge::EngineVmaDestroyImage(
+          vma_alloc, image_bits_,
+          static_cast<vma_bridge::Allocation_T*>(image_alloc_));
+      image_bits_ = 0;
+      image_alloc_ = nullptr;
+      image_live_ = false;
+    }
+    if (vma_alloc != nullptr && staging_alloc_ != nullptr) {
+      vma_bridge::EngineVmaDestroyBuffer(
+          vma_alloc, staging_bits_,
+          static_cast<vma_bridge::Allocation_T*>(staging_alloc_));
+      staging_bits_ = 0;
+      staging_alloc_ = nullptr;
+      staging_mapped_ = nullptr;
+    }
+    if (p_vkDestroyPipeline != nullptr && pipeline_ != nullptr) {
+      p_vkDestroyPipeline(device_, pipeline_, nullptr);
+      pipeline_ = nullptr;
+    }
+    if (p_vkDestroyPipelineLayout != nullptr && pipe_layout_ != nullptr) {
+      p_vkDestroyPipelineLayout(device_, pipe_layout_, nullptr);
+      pipe_layout_ = nullptr;
+    }
+    if (p_vkDestroyDescriptorSetLayout != nullptr && set_layout_ != nullptr) {
+      p_vkDestroyDescriptorSetLayout(
+          device_, static_cast<VkDescriptorSetLayout>(set_layout_), nullptr);
+      set_layout_ = nullptr;
+    }
+    if (p_vkDestroyShaderModule != nullptr) {
+      for (int i = 0; i < 2; ++i) {
+        if (modules_[i] != nullptr) {
+          p_vkDestroyShaderModule(device_, modules_[i], nullptr);
+          modules_[i] = nullptr;
+        }
+      }
+    }
+  } else {
+    // Never created, or the device is already gone: drop handles without
+    // driver calls (same rule as ForwardRenderer).
+    modules_[0] = modules_[1] = nullptr;
+    pipeline_ = nullptr;
+    pipe_layout_ = nullptr;
+    set_layout_ = nullptr;
+    pool_ = nullptr;
+    set_ = nullptr;
+    sampler_ = nullptr;
+    image_view_ = nullptr;
+    image_bits_ = 0;
+    image_alloc_ = nullptr;
+    staging_bits_ = 0;
+    staging_alloc_ = nullptr;
+    staging_mapped_ = nullptr;
+    image_live_ = false;
+  }
+  module_count_ = 0;
+  ready_ = false;
+  dirty_ = false;
+  image_shader_read_ = false;
+  device_ = nullptr;
+  // Drop create-time-only procs so a use-after-destroy reads null, not
+  // stale entry points (same pattern as GiFrameGraph).
+  proc_create_module_ = nullptr;
+  proc_destroy_module_ = nullptr;
+  proc_create_pipelines_ = nullptr;
+  proc_destroy_pipeline_ = nullptr;
+  proc_create_layout_ = nullptr;
+  proc_destroy_layout_ = nullptr;
+  proc_create_ds_layout_ = nullptr;
+  proc_destroy_ds_layout_ = nullptr;
+  proc_create_pool_ = nullptr;
+  proc_destroy_pool_ = nullptr;
+  proc_alloc_ds_ = nullptr;
+  proc_update_ds_ = nullptr;
+  proc_bind_ds_ = nullptr;
+  proc_create_sampler_ = nullptr;
+  proc_destroy_sampler_ = nullptr;
+  proc_create_view_ = nullptr;
+  proc_destroy_view_ = nullptr;
+  proc_bind_pipeline_ = nullptr;
+  proc_cmd_viewport_ = nullptr;
+  proc_cmd_scissor_ = nullptr;
+  proc_cmd_draw_ = nullptr;
+  proc_cmd_push_ = nullptr;
+  proc_begin_rendering_ = nullptr;
+  proc_end_rendering_ = nullptr;
+  proc_cmd_copy_b2i_ = nullptr;
+  proc_cmd_barrier_ = nullptr;
+}
+
+auto HudOverlay::update(const std::uint8_t* pixels) noexcept -> Status {
+  if (!ready_) {
+    return MakeFail(StatusCode::kNotInitialized, "hud not built");
+  }
+  if (pixels == nullptr) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud null pixels");
+  }
+  if (staging_mapped_ == nullptr) {
+    return MakeFail(StatusCode::kNotInitialized, "hud no staging");
+  }
+  // Persistent mapped staging (host-visible coherent, same as GpuMesh):
+  // plain byte copy, no struct overlay (Sonar-safe, no memcpy-on-object).
+  auto* dst = static_cast<std::uint8_t*>(staging_mapped_);
+  for (std::uint32_t i = 0; i < kHudFrameBytes; ++i) {
+    dst[i] = pixels[i];
+  }
+  dirty_ = true;
+  return MakeOk();
+}
+
+auto HudOverlay::record_upload(VkCommandBuffer cmd) noexcept -> Status {
+  if (!ready_) {
+    return MakeFail(StatusCode::kNotInitialized, "hud not built");
+  }
+  if (cmd == nullptr) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud null cmd");
+  }
+  if (!dirty_) {
+    return MakeOk();  // nothing staged: image already holds the frame.
+  }
+  auto p_vkCmdCopyBufferToImage =
+      reinterpret_cast<PFN_vkCmdCopyBufferToImage>(proc_cmd_copy_b2i_);
+  auto p_vkCmdBarrier =
+      reinterpret_cast<PFN_vkCmdPipelineBarrier2>(proc_cmd_barrier_);
+  if (p_vkCmdCopyBufferToImage == nullptr || p_vkCmdBarrier == nullptr) {
+    return MakeFail(StatusCode::kVulkanLoaderFailed, "hud no upload entry");
+  }
+  if (!image_live_) {
+    return MakeFail(StatusCode::kNotInitialized, "hud no image");
+  }
+  const VkImage img = reinterpret_cast<VkImage>(
+      static_cast<std::uintptr_t>(image_bits_));
+  const VkBuffer staging = reinterpret_cast<VkBuffer>(
+      static_cast<std::uintptr_t>(staging_bits_));
+  // First transition: UNDEFINED -> TRANSFER_DST (once; after the first
+  // upload the image rests in SHADER_READ and only needs
+  // SHADER_READ -> TRANSFER_DST -> SHADER_READ round trips).
+  {
+    VkImageMemoryBarrier2 b{};
+    b.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2;
+    b.srcStageMask = VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT;
+    b.srcAccessMask = 0;
+    b.dstStageMask = VK_PIPELINE_STAGE_2_COPY_BIT;
+    b.dstAccessMask = VK_ACCESS_2_TRANSFER_WRITE_BIT;
+    b.oldLayout = image_shader_read_
+                      ? VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
+                      : VK_IMAGE_LAYOUT_UNDEFINED;
+    b.newLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
+    b.image = img;
+    b.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+    b.subresourceRange.baseMipLevel = 0;
+    b.subresourceRange.levelCount = 1;
+    b.subresourceRange.baseArrayLayer = 0;
+    b.subresourceRange.layerCount = 1;
+    if (image_shader_read_) {
+      b.srcStageMask = VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT;
+      b.srcAccessMask = VK_ACCESS_2_SHADER_READ_BIT;
+    }
+    VkDependencyInfo di{};
+    di.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO;
+    di.imageMemoryBarrierCount = 1;
+    di.pImageMemoryBarriers = &b;
+    p_vkCmdBarrier(cmd, &di);
+  }
+  VkBufferImageCopy region{};
+  region.bufferOffset = 0;
+  region.bufferRowLength = 0;  // tightly packed (640x4 = 2560 B/row)
+  region.bufferImageHeight = 0;
+  region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+  region.imageSubresource.mipLevel = 0;
+  region.imageSubresource.baseArrayLayer = 0;
+  region.imageSubresource.layerCount = 1;
+  region.imageOffset.x = 0;
+  region.imageOffset.y = 0;
+  region.imageOffset.z = 0;
+  region.imageExtent.width = kHudFrameW;
+  region.imageExtent.height = kHudFrameH;
+  region.imageExtent.depth = 1;
+  p_vkCmdCopyBufferToImage(cmd, staging, img,
+                           VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &region);
+  // Second transition: TRANSFER_DST -> SHADER_READ (frag sampling).
+  {
+    VkImageMemoryBarrier2 b{};
+    b.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2;
+    b.srcStageMask = VK_PIPELINE_STAGE_2_COPY_BIT;
+    b.srcAccessMask = VK_ACCESS_2_TRANSFER_WRITE_BIT;
+    b.dstStageMask = VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT;
+    b.dstAccessMask = VK_ACCESS_2_SHADER_READ_BIT;
+    b.oldLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
+    b.newLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
+    b.image = img;
+    b.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+    b.subresourceRange.baseMipLevel = 0;
+    b.subresourceRange.levelCount = 1;
+    b.subresourceRange.baseArrayLayer = 0;
+    b.subresourceRange.layerCount = 1;
+    VkDependencyInfo di{};
+    di.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO;
+    di.imageMemoryBarrierCount = 1;
+    di.pImageMemoryBarriers = &b;
+    p_vkCmdBarrier(cmd, &di);
+  }
+  dirty_ = false;
+  image_shader_read_ = true;
+  return MakeOk();
+}
+
+auto HudOverlay::continue_hud_pass(VkCommandBuffer cmd,
+                                   VkImageView color_view,
+                                   VkExtent2D extent) noexcept -> Status {
+  if (pipeline_ == nullptr || pipe_layout_ == nullptr) {
+    return MakeFail(StatusCode::kNotInitialized, "hud not built");
+  }
+  if (cmd == nullptr || color_view == nullptr || extent.width == 0 ||
+      extent.height == 0) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud bad pass arg");
+  }
+  const auto p_vkCmdBeginRendering = reinterpret_cast<PFN_vkCmdBeginRendering>(proc_begin_rendering_);
+  const auto p_vkCmdSetViewport = reinterpret_cast<PFN_vkCmdSetViewport>(proc_cmd_viewport_);
+  const auto p_vkCmdSetScissor = reinterpret_cast<PFN_vkCmdSetScissor>(proc_cmd_scissor_);
+  const auto p_vkCmdBindPipeline = reinterpret_cast<PFN_vkCmdBindPipeline>(proc_bind_pipeline_);
+  const bool pass_procs_ok = p_vkCmdBeginRendering != nullptr && p_vkCmdSetViewport != nullptr &&
+                             p_vkCmdSetScissor != nullptr && p_vkCmdBindPipeline != nullptr;
+  if (!pass_procs_ok) {
+    return MakeFail(StatusCode::kVulkanLoaderFailed, "hud no pass entry");
+  }
+  HudFixed pass{};
+  fill_hud_pass(&pass, color_view, extent);
+  p_vkCmdBeginRendering(cmd, &pass.ri);
+  p_vkCmdSetViewport(cmd, 0, 1, &pass.vp);
+  p_vkCmdSetScissor(cmd, 0, 1, &pass.scissor);
+  p_vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline_);
+  return MakeOk();
+}
+
+auto HudOverlay::end_hud_pass(VkCommandBuffer cmd) noexcept -> Status {
+  if (pipeline_ == nullptr || pipe_layout_ == nullptr) {
+    return MakeFail(StatusCode::kNotInitialized, "hud not built");
+  }
+  if (cmd == nullptr) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud bad end arg");
+  }
+  auto p_vkCmdEndRendering =
+      reinterpret_cast<PFN_vkCmdEndRendering>(proc_end_rendering_);
+  if (p_vkCmdEndRendering == nullptr) {
+    return MakeFail(StatusCode::kVulkanLoaderFailed, "hud no end entry");
+  }
+  p_vkCmdEndRendering(cmd);
+  return MakeOk();
+}
+
+auto HudOverlay::record_draw(VkCommandBuffer cmd, float vp_w,
+                             float vp_h) noexcept -> Status {
+  if (pipeline_ == nullptr || pipe_layout_ == nullptr) {
+    return MakeFail(StatusCode::kNotInitialized, "hud not built");
+  }
+  if (cmd == nullptr || !(vp_w > 0.0F) || !(vp_h > 0.0F)) {
+    return MakeFail(StatusCode::kInvalidArgument, "hud bad draw arg");
+  }
+  auto p_vkCmdPushConstants =
+      reinterpret_cast<PFN_vkCmdPushConstants>(proc_cmd_push_);
+  auto p_vkCmdDraw = reinterpret_cast<PFN_vkCmdDraw>(proc_cmd_draw_);
+  auto p_vkCmdBindDescriptorSets =
+      reinterpret_cast<PFN_vkCmdBindDescriptorSets>(proc_bind_ds_);
+  if (p_vkCmdPushConstants == nullptr || p_vkCmdDraw == nullptr ||
+      p_vkCmdBindDescriptorSets == nullptr) {
+    return MakeFail(StatusCode::kVulkanLoaderFailed, "hud no draw entry");
+  }
+  if (set_ == nullptr) {
+    return MakeFail(StatusCode::kNotInitialized, "hud no set");
+  }
+  const VkDescriptorSet draw_set = static_cast<VkDescriptorSet>(set_);
+  p_vkCmdBindDescriptorSets(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS,
+                            pipe_layout_, 0, 1, &draw_set, 0, nullptr);
+  HudPush push{};
+  push.viewport_px[0] = vp_w;
+  push.viewport_px[1] = vp_h;
+  p_vkCmdPushConstants(cmd, pipe_layout_,
+                       VK_SHADER_STAGE_VERTEX_BIT |
+                           VK_SHADER_STAGE_FRAGMENT_BIT,
+                       0, static_cast<std::uint32_t>(sizeof(HudPush)), &push);
+  // Exactly one fullscreen-triangle draw: 3 verts, no vertex buffers.
+  p_vkCmdDraw(cmd, 3, 1, 0, 0);
+  return MakeOk();
+}
+
+#else
+
+auto HudOverlay::create(VulkanDevice& /*dev*/, VkFormat /*color_format*/,
+                        const std::uint32_t* /*vert_spv*/,
+                        std::size_t /*vert_words*/,
+                        const std::uint32_t* /*frag_spv*/,
+                        std::size_t /*frag_words*/) noexcept -> Status {
+  return MakeFail(StatusCode::kVulkanLoaderFailed, "no Vulkan SDK");
+}
+
+auto HudOverlay::destroy() noexcept -> void {
+  modules_[0] = modules_[1] = nullptr;
+  pipeline_ = nullptr;
+  pipe_layout_ = nullptr;
+  module_count_ = 0;
+  ready_ = false;
+  dirty_ = false;
+  image_shader_read_ = false;
+}
+
+auto HudOverlay::update(const std::uint8_t* /*pixels*/) noexcept -> Status {
+  return MakeFail(StatusCode::kVulkanLoaderFailed, "no Vulkan SDK");
+}
+
+auto HudOverlay::record_upload(VkCommandBuffer /*cmd*/) noexcept -> Status {
+  return MakeFail(StatusCode::kVulkanLoaderFailed, "no Vulkan SDK");
+}
+
+auto HudOverlay::continue_hud_pass(VkCommandBuffer /*cmd*/,
+                                   VkImageView /*color_view*/,
+                                   VkExtent2D /*extent*/) noexcept -> Status {
+  return MakeFail(StatusCode::kVulkanLoaderFailed, "no Vulkan SDK");
+}
+
+auto HudOverlay::end_hud_pass(VkCommandBuffer /*cmd*/) noexcept -> Status {
+  return MakeFail(StatusCode::kVulkanLoaderFailed, "no Vulkan SDK");
+}
+
+auto HudOverlay::record_draw(VkCommandBuffer /*cmd*/, float /*vp_w*/,
+                             float /*vp_h*/) noexcept -> Status {
+  return MakeFail(StatusCode::kVulkanLoaderFailed, "no Vulkan SDK");
+}
+
+#endif
+
+}  // namespace engine::renderer
@@ -70,6 +70,13 @@ auto EngineVmaCreateIdImage(Allocator_T* alloc, std::uint32_t width,
 auto EngineVmaCreateColorImage(Allocator_T* alloc, std::uint32_t width,
                               std::uint32_t height,
                               DepthImageBundle* out) -> int;
+// P5-04-followup: R8G8B8A8_UNORM sampled image (TRANSFER_DST + SAMPLED,
+// device-local) for the HUD overlay texture. Same shape as the color
+// twin, but a SAMPLED target (never an attachment): the overlay uploads
+// the CPU HUD backbuffer into it and samples it in the composite pass.
+auto EngineVmaCreateHudImage(Allocator_T* alloc, std::uint32_t width,
+                             std::uint32_t height,
+                             DepthImageBundle* out) -> int;
 auto EngineVmaDestroyImage(Allocator_T* alloc, std::uint64_t image_bits,
                           Allocation_T* handle) -> void;
 }  // extern "C"
@@ -227,13 +227,15 @@ auto EngineVmaCreateDepthImage(Allocator_T* alloc_raw, std::uint32_t width,
  return 0;
 }

-// P3-06: R32G32_UINT id image (COLOR_ATTACHMENT + TRANSFER_SRC, device-local)
-// for the object-id pick target. Same shape as the depth twin; lavapipe
-// supports R32G32_UINT as a color attachment (integer formats render without
-// blending — the pick pipeline sets attachmentCount 0 for blend).
-auto EngineVmaCreateIdImage(Allocator_T* alloc_raw, std::uint32_t width,
-                            std::uint32_t height,
-                            DepthImageBundle* out) -> int {
+namespace {
+
+// Shared device-local 2D image (one struct-fill site): the id/color/hud
+// twins differ only in format + usage (Sonar duplication gate). Returns 0
+// on success, -1 on bad args or vma failure.
+auto vma_create_device_image(Allocator_T* alloc_raw, VkFormat format,
+                             VkImageUsageFlags usage, std::uint32_t width,
+                             std::uint32_t height,
+                             DepthImageBundle* out) -> int {
  VmaAllocator alloc = reinterpret_cast<VmaAllocator>(alloc_raw);
  if (alloc == nullptr || out == nullptr || width == 0 || height == 0) {
    return -1;
@@ -241,7 +243,7 @@ auto EngineVmaCreateIdImage(Allocator_T* alloc_raw, std::uint32_t width,
  VkImageCreateInfo ic{};
  ic.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
  ic.imageType = VK_IMAGE_TYPE_2D;
-  ic.format = VK_FORMAT_R32G32_UINT;
+  ic.format = format;
  ic.extent.width = width;
  ic.extent.height = height;
  ic.extent.depth = 1;
@@ -249,8 +251,7 @@ auto EngineVmaCreateIdImage(Allocator_T* alloc_raw, std::uint32_t width,
  ic.arrayLayers = 1;
  ic.samples = VK_SAMPLE_COUNT_1_BIT;
  ic.tiling = VK_IMAGE_TILING_OPTIMAL;
-  ic.usage = static_cast<VkImageUsageFlags>(
-      VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT);
+  ic.usage = usage;
  ic.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
  ic.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
  VmaAllocationCreateInfo ac{};
@@ -267,43 +268,46 @@ auto EngineVmaCreateIdImage(Allocator_T* alloc_raw, std::uint32_t width,
  return 0;
 }

+}  // namespace
+
+// P3-06: R32G32_UINT id image (COLOR_ATTACHMENT + TRANSFER_SRC, device-local)
+// for the object-id pick target. Same shape as the depth twin; lavapipe
+// supports R32G32_UINT as a color attachment (integer formats render without
+// blending — the pick pipeline sets attachmentCount 0 for blend).
+auto EngineVmaCreateIdImage(Allocator_T* alloc_raw, std::uint32_t width,
+                            std::uint32_t height,
+                            DepthImageBundle* out) -> int {
+  return vma_create_device_image(
+      alloc_raw, VK_FORMAT_R32G32_UINT,
+      static_cast<VkImageUsageFlags>(VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT |
+                                     VK_IMAGE_USAGE_TRANSFER_SRC_BIT),
+      width, height, out);
+}
+
 // P3-02: R8G8B8A8_UNORM color image (COLOR_ATTACHMENT + TRANSFER_SRC,
 // device-local) for the offscreen color target (viewport readback +
 // editor ViewportControl). Same device-local shape as the id twin.
 auto EngineVmaCreateColorImage(Allocator_T* alloc_raw, std::uint32_t width,
                               std::uint32_t height,
                               DepthImageBundle* out) -> int {
-  VmaAllocator alloc = reinterpret_cast<VmaAllocator>(alloc_raw);
-  if (alloc == nullptr || out == nullptr || width == 0 || height == 0) {
-    return -1;
-  }
-  VkImageCreateInfo ic{};
-  ic.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
-  ic.imageType = VK_IMAGE_TYPE_2D;
-  ic.format = VK_FORMAT_R8G8B8A8_UNORM;
-  ic.extent.width = width;
-  ic.extent.height = height;
-  ic.extent.depth = 1;
-  ic.mipLevels = 1;
-  ic.arrayLayers = 1;
-  ic.samples = VK_SAMPLE_COUNT_1_BIT;
-  ic.tiling = VK_IMAGE_TILING_OPTIMAL;
-  ic.usage = static_cast<VkImageUsageFlags>(
-      VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT);
-  ic.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
-  ic.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
-  VmaAllocationCreateInfo ac{};
-  ac.requiredFlags = static_cast<VkMemoryPropertyFlags>(
-      VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
-  VkImage img = VK_NULL_HANDLE;
-  VmaAllocation handle = nullptr;
-  if (vmaCreateImage(alloc, &ic, &ac, &img, &handle, nullptr) != VK_SUCCESS) {
-    return -1;
-  }
-  out->image_bits =
-      static_cast<std::uint64_t>(reinterpret_cast<std::uintptr_t>(img));
-  out->alloc = reinterpret_cast<Allocation_T*>(handle);
-  return 0;
+  return vma_create_device_image(
+      alloc_raw, VK_FORMAT_R8G8B8A8_UNORM,
+      static_cast<VkImageUsageFlags>(VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT |
+                                     VK_IMAGE_USAGE_TRANSFER_SRC_BIT),
+      width, height, out);
+}
+
+// P5-04-followup: R8G8B8A8_UNORM sampled image (TRANSFER_DST + SAMPLED,
+// device-local) for the HUD overlay texture. Same device-local shape as
+// the color twin; usage differs (never an attachment, never TRANSFER_SRC).
+auto EngineVmaCreateHudImage(Allocator_T* alloc_raw, std::uint32_t width,
+                             std::uint32_t height,
+                             DepthImageBundle* out) -> int {
+  return vma_create_device_image(
+      alloc_raw, VK_FORMAT_R8G8B8A8_UNORM,
+      static_cast<VkImageUsageFlags>(VK_IMAGE_USAGE_TRANSFER_DST_BIT |
+                                     VK_IMAGE_USAGE_SAMPLED_BIT),
+      width, height, out);
 }

 auto EngineVmaDestroyImage(Allocator_T* alloc_raw, std::uint64_t image_bits,
@@ -1273,6 +1273,29 @@ set_tests_properties(engine_ecs_particles_frame PROPERTIES
    TIMEOUT 300
    ${ENGINE_TEST_VIDEO_ENV})

+# P5-04-followup: HUD composite in the ECS frame (frames through the real
+# RenderOne path with a bound GameUi + hud-on differs from hud-off +
+# composite matches the CPU backbuffer + unbind restores clear).
+add_executable(engine_hud_composite test_hud_composite.cpp golden_stb.cpp)
+
+target_link_libraries(engine_hud_composite PRIVATE engine_core)
+
+engine_apply_base_flags(engine_hud_composite)
+
+if(NOT MSVC)
+  set_source_files_properties(golden_stb.cpp PROPERTIES COMPILE_OPTIONS "-w")
+endif()
+
+target_compile_definitions(engine_hud_composite PRIVATE
+    ENGINE_GOLDEN_DIR="${CMAKE_SOURCE_DIR}/native/tests/golden"
+    ENGINE_GOLDEN_OUT_DIR="${CMAKE_CURRENT_BINARY_DIR}/golden_out"
+    ENGINE_UI_FONT_DIR="${CMAKE_BINARY_DIR}/ui_fonts")
+
+add_test(NAME engine_hud_composite COMMAND engine_hud_composite)
+set_tests_properties(engine_hud_composite PROPERTIES
+    TIMEOUT 300
+    ${ENGINE_TEST_VIDEO_ENV})
+
 # P3-09: console/profiler GPU timer (FrameGpuTimer timestamp round trip).
 add_executable(engine_frame_gpu_timer test_frame_gpu_timer.cpp)

@@ -1371,4 +1394,9 @@ if(WIN32)
            $<TARGET_RUNTIME_DLLS:engine_ecs_particles_frame>
            $<TARGET_FILE_DIR:engine_ecs_particles_frame>
        COMMAND_EXPAND_LISTS)
+    add_custom_command(TARGET engine_hud_composite POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            $<TARGET_RUNTIME_DLLS:engine_hud_composite>
+            $<TARGET_FILE_DIR:engine_hud_composite>
+        COMMAND_EXPAND_LISTS)
 endif()
@@ -249,7 +249,7 @@ auto main() -> int {
  failures += check(offsetof(EcsChunkView, world) == 8, "abi: EcsChunkView.world @ 8");
  failures += check(offsetof(EcsChunkView, entities) == 16, "abi: EcsChunkView.entities @ 16");
  failures += check(offsetof(EcsChunkView, user_data) == 40, "abi: EcsChunkView.user_data @ 40");
-  failures += check(sizeof(EngineApiTable) == 1000, "abi: EngineApiTable 1000B (ABI 4.17 physics_drain_events tail)");
+  failures += check(sizeof(EngineApiTable) == 1008, "abi: EngineApiTable 1008B (ABI 4.19 renderer_attach_ui tail)");
  failures += check(sizeof(EngineInputState) == 1668, "abi: EngineInputState 1668B");
  failures += check(offsetof(EngineInputState, mouse_x) == 1536, "abi: EngineInputState.mouse_x @ 1536");
  failures += check(offsetof(EngineInputState, mouse_buttons) == 1552, "abi: EngineInputState.mouse_buttons @ 1552");
@@ -407,6 +407,18 @@ auto main() -> int {
  }
  failures += check(offsetof(EngineApiTable, physics_drain_events) == 992,
                    "abi: physics_drain_events @ 992 (4.17 tail end)");
+  // P5-04-followup HUD-composite tail (ABI 4.19): 1 appended entry after
+  // the 4.17 collision-event tail (physics_drain_events @ 992).
+  failures += check(api->renderer_attach_ui != nullptr,
+                    "abi: renderer_attach_ui set");
+  if (api->renderer_attach_ui != nullptr) {
+    failures += check(api->renderer_attach_ui(nullptr, nullptr) != 0,
+                      "abi: renderer_attach_ui null renderer fails");
+  } else {
+    failures += check(false, "abi: renderer_attach_ui null renderer fails");
+  }
+  failures += check(offsetof(EngineApiTable, renderer_attach_ui) == 1000,
+                    "abi: renderer_attach_ui @ 1000 (4.19 tail end)");
  // P2-05 3D collision-event mirror: 32-byte record matching the 2D path.
  failures += check(sizeof(EngineCollisionEvent) == 32, "abi: EngineCollisionEvent 32B");
  failures += check(offsetof(EngineCollisionEvent, point_x) == 16,
@@ -0,0 +1,302 @@
+// test_hud_composite.cpp — P5-04-followup acceptance (native CTest).
+//
+// GPU test through the REAL frame path: the ABI EngineRenderer owns the
+// frame loop (RenderOne in renderer_bridge.cpp). When a GameUi is bound
+// via renderer_attach_ui, RenderOne re-renders the HUD into its CPU
+// backbuffer, staging-uploads it, and composites it OVER the frame as a
+// textured fullscreen triangle (LOAD pass). This TU proves:
+//   1. HUD-ON composite differs from HUD-OFF clear (the overlay is not a
+//      transparent no-op — same alpha-proof shape as the P5-05 plume
+//      differs-from-clear gate).
+//   2. HUD-ON matches the CPU backbuffer the UI renders (the composite
+//      carries RmlUi pixels, not a placeholder): downsample the 640x360
+//      swapchain readback against ui_copy_frame bytes within golden
+//      tolerance (±2/channel, ≤0.1% differing pixels).
+//
+// World: one main Camera + one DirectionalLight, NO meshes (mesh pass
+// clears; the HUD is the whole image). 640x360 so the composite is 1:1
+// with the backbuffer — no upscale blur to justify.
+//
+// Frame capture: renderer_screenshot writes the last presented RGBA frame
+// to a PNG; GoldenLoadPng decodes it back (same stb decode the harness
+// uses for checked-in goldens). The CPU backbuffer comes from the same
+// ABI (ui_create/ui_render/ui_copy_frame) the frame composites.
+//
+// Rules: SDL_VIDEO_DRIVER=offscreen (ctest property); ENGINE_REQUIRE_GPU=1
+// turns no-device paths into [FAIL] (gpu_required.hpp), never [SKIP].
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <span>
+#include <string>
+#include <vector>
+
+#include "engine/bridge/engine_abi.h"
+#include "engine/ecs/ecs_render_components.hpp"
+#include "engine/ecs/ecs_world.hpp"
+#include "engine/ecs/transform.hpp"
+#include "engine/ui/game_ui.hpp"
+#include "flecs.h"
+#include "golden_compare.hpp"
+#include "gpu_required.hpp"
+
+namespace {
+
+using engine::ecs::Camera;
+using engine::ecs::DirectionalLight;
+using engine::ecs::LocalTransform;
+
+auto failures = 0;
+
+void check(bool hud_ok, const char* name) {
+  std::printf("[%s] %s\n", hud_ok ? "PASS" : "FAIL", name);
+  failures += hud_ok ? 0 : 1;
+}
+
+// Real-type layout guards (same static_asserts as test_ecs_render.cpp):
+// the ABI component_register sizes below must match these exactly.
+static_assert(sizeof(Camera) == 16, "Camera is 16 bytes");
+static_assert(alignof(Camera) == 4, "Camera align drifted");
+static_assert(sizeof(DirectionalLight) == 16, "DirectionalLight is 16 bytes");
+static_assert(sizeof(LocalTransform) == 64, "LocalTransform is 64 bytes");
+
+auto make_local(float tx, float ty, float tz) -> LocalTransform {
+  LocalTransform l{};
+  l.px = tx;
+  l.py = ty;
+  l.pz = tz;
+  // Value-init zeroes quat/scale, so set them explicitly: propagate()
+  // composes World from these.
+  l.qw = 1.0F;
+  l.sx = 1.0F;
+  l.sy = 1.0F;
+  l.sz = 1.0F;
+  return l;
+}
+
+// Minimal camera+light world (no meshes, no emitters). Returns nullptr on
+// failure (check already recorded).
+auto make_world(const EngineApiTable* api) -> EngineWorld* {
+  EngineWorld* world = api->world_create();
+  if (world == nullptr) {
+    check(false, "hud-composite: world_create");
+    return nullptr;
+  }
+  const std::uint64_t cam_id = api->component_register(
+      world, "Engine.Runtime.Camera", sizeof(Camera), alignof(Camera));
+  const std::uint64_t light_id = api->component_register(
+      world, "Engine.Runtime.DirectionalLight", sizeof(DirectionalLight),
+      alignof(DirectionalLight));
+  const std::uint64_t local_id = api->component_register(
+      world, "LocalTransform", sizeof(LocalTransform),
+      alignof(LocalTransform));
+  bool ok = cam_id != 0 && light_id != 0 && local_id != 0;
+  if (!ok) {
+    check(false, "hud-composite: component_register");
+    api->world_destroy(world);
+    return nullptr;
+  }
+  // Camera looks straight down -Z at the origin HUD plane (distinct from
+  // the particle TU's angled view: this frame has no world content).
+  const std::uint64_t cam_e = api->entity_create(world);
+  Camera c{};
+  c.fov_y_rad = 45.0F * 3.14159265F / 180.0F;
+  c.near_z = 0.05F;
+  c.far_z = 50.0F;
+  c.is_main = 1;
+  ok = ok && api->entity_set(world, cam_e, cam_id, &c, sizeof(c)) == 0;
+  const LocalTransform cam_lt = make_local(0.0F, 0.0F, 3.0F);
+  ok = ok && api->entity_set(world, cam_e, local_id, &cam_lt, sizeof(cam_lt)) == 0;
+  const std::uint64_t sun_e = api->entity_create(world);
+  DirectionalLight sun{};
+  sun.direction[0] = 0.0F;
+  sun.direction[1] = 0.0F;
+  sun.direction[2] = -1.0F;
+  ok = ok && api->entity_set(world, sun_e, light_id, &sun, sizeof(sun)) == 0;
+  ok = ok && api->world_propagate(world) == 0;
+  if (!ok) {
+    check(false, "hud-composite: world build");
+    api->world_destroy(world);
+    return nullptr;
+  }
+  return world;
+}
+
+// Present `frames` frames on `renderer`, then screenshot to `png_path` and
+// decode it. Empty on failure (check already recorded); `no_device_out`
+// stays false — renderer creation is the caller's no-device gate.
+auto shot(const EngineApiTable* api, EngineRenderer* renderer,
+          const std::string& png_path, std::uint32_t w, std::uint32_t h,
+          int frames, const char* tag) -> std::vector<std::uint8_t> {
+  for (int f = 0; f < frames; ++f) {
+    if (api->renderer_frame(renderer) != 0) {
+      check(false, tag);  // post-creation frame failure: hard FAIL
+      return {};
+    }
+  }
+  if (api->renderer_screenshot(renderer, png_path.c_str()) != 0) {
+    check(false, tag);  // post-creation capture failure: hard FAIL
+    return {};
+  }
+  std::vector<std::uint8_t> px;
+  int pw = 0;
+  int ph = 0;
+  if (!engine::test::GoldenLoadPng(png_path, px, pw, ph) ||
+      pw != static_cast<int>(w) || ph != static_cast<int>(h) ||
+      px.size() != static_cast<std::size_t>(w) * h * 4) {
+    check(false, tag);  // post-creation decode failure: hard FAIL
+    return {};
+  }
+  return px;
+}
+
+void test_hud_composite() {
+  // 640x360 = the HUD backbuffer size: the composite is 1:1, so the
+  // screenshot compares against ui_copy_frame bytes with no resampling.
+  constexpr std::uint32_t kW = engine::ui::kUiFrameW;
+  constexpr std::uint32_t kH = engine::ui::kUiFrameH;
+  constexpr int kFrames = 8;
+
+  const EngineApiTable* api = engine_get_api_table();
+  check(api != nullptr, "hud-composite: api table non-NULL");
+  if (api == nullptr) {
+    return;
+  }
+  check(api->renderer_attach_ui != nullptr,
+        "hud-composite: renderer_attach_ui set");
+  if (api->renderer_attach_ui == nullptr) {
+    return;
+  }
+
+  std::string out_dir = ENGINE_GOLDEN_OUT_DIR;
+  if (!out_dir.empty() && out_dir.back() != '/') {
+    out_dir.push_back('/');
+  }
+  (void)engine::test::GoldenMkdirP(out_dir);
+  const std::string on_png = out_dir + "p5_04_hud_composite_640x360.shot.png";
+  const std::string off_png =
+      out_dir + "p5_04_hud_composite_off.shot.png";
+
+  EngineWorld* world = make_world(api);
+  if (world == nullptr) {
+    return;
+  }
+  EngineRenderer* renderer =
+      api->renderer_create(world, kW, kH, ENGINE_RENDERER_HIDDEN);
+  if (renderer == nullptr) {
+    api->world_destroy(world);
+    // Renderer creation itself failed: no device or no display is a
+    // skip (gpu_missing returns 1 under ENGINE_REQUIRE_GPU=1).
+    failures += gpu_missing("hud-composite: renderer created");
+    return;
+  }
+  check(true, "hud-composite: renderer created");
+
+  // ABI misuse gates (fail closed, no GPU touched).
+  check(api->renderer_attach_ui(nullptr, nullptr) != 0,
+        "hud-composite: null renderer fails");
+#ifdef ENGINE_UI_FONT_DIR
+  constexpr const char* kFontDir = ENGINE_UI_FONT_DIR;
+#else
+  constexpr const char* kFontDir = ".";
+#endif
+  EngineUi* ui = api->ui_create(kFontDir);
+  check(ui != nullptr, "hud-composite: ui_create");
+  if (ui == nullptr) {
+    api->renderer_destroy(renderer);
+    api->world_destroy(world);
+    return;
+  }
+
+  // Golden fixture: the default HUD from P5-04 (SCORE 0 / START).
+  check(api->ui_set_text(ui, "lbl", "SCORE 0") == 0,
+        "hud-composite: golden label reset");
+  check(api->ui_set_text(ui, "btn", "START") == 0,
+        "hud-composite: golden button reset");
+  std::vector<std::uint8_t> cpu(static_cast<std::size_t>(kW) * kH * 4, 0);
+  check(api->ui_render(ui) == 0, "hud-composite: cpu hud renders");
+  check(api->ui_copy_frame(ui, cpu.data(),
+                           static_cast<std::uint32_t>(cpu.size())) == 0,
+        "hud-composite: cpu hud copied");
+
+  // 1. HUD-OFF baseline: cleared frame (mesh pass CLEARs to black; the
+  // default HUD top bar #2e3440 is opaque so HUD-ON must differ).
+  const std::vector<std::uint8_t> off =
+      shot(api, renderer, off_png, kW, kH, kFrames,
+           "hud-composite: hud-off frames presented");
+  check(!off.empty(), "hud-composite: hud-off frames presented");
+
+  // 2. Bind, then HUD-ON: RenderOne composites the HUD OVER the frame.
+  check(api->renderer_attach_ui(renderer, ui) == 0,
+        "hud-composite: renderer_attach_ui binds");
+  const std::vector<std::uint8_t> on = shot(api, renderer, on_png, kW, kH,
+                                            kFrames,
+                                            "hud-composite: hud-on rendered");
+  check(!on.empty(), "hud-composite: hud-on frames presented");
+
+  if (!off.empty() && !on.empty()) {
+    const bool differs =
+        off.size() == on.size() &&
+        std::memcmp(off.data(), on.data(), on.size()) != 0;
+    check(differs, "hud-composite: hud-on differs from hud-off");
+    if (differs) {
+      // The composite must carry the RmlUi pixels: compare the readback
+      // against the CPU backbuffer within golden tolerance (±2/channel,
+      // ≤0.1% differing pixels — the same gate as golden_compare), RGB
+      // channels only. Alpha is presentation-destroyed by design: the
+      // swapchain is opaque (capture alpha is always 255) while the CPU
+      // backbuffer carries real alpha (0 in empty regions, partial on
+      // glyph edges), so the A channel can never round-trip. The blend
+      // state (ONE/ONE_MINUS_SRC_ALPHA over the black mesh-pass clear)
+      // reproduces the premultiplied CPU RGB exactly.
+      std::size_t diff_px = 0;
+      const std::size_t npx = static_cast<std::size_t>(kW) * kH;
+      for (std::size_t p = 0; p < npx; ++p) {
+        bool diff = false;
+        for (int c = 0; c < 3; ++c) {
+          const int a = static_cast<int>(on[p * 4 + c]);
+          const int b = static_cast<int>(cpu[p * 4 + c]);
+          const int d = a >= b ? a - b : b - a;
+          if (d > engine::test::kGoldenChannelTol) {
+            diff = true;
+            break;
+          }
+        }
+        if (diff) {
+          ++diff_px;
+        }
+      }
+      const double frac =
+          static_cast<double>(diff_px) / static_cast<double>(npx);
+      check(frac <= engine::test::kGoldenMaxFrac,
+            "hud-composite: composite matches cpu backbuffer");
+    }
+    // 3. Unbind restores the cleared frame (binding is borrow + clear).
+    check(api->renderer_attach_ui(renderer, nullptr) == 0,
+          "hud-composite: renderer_attach_ui unbinds");
+    const std::vector<std::uint8_t> cleared =
+        shot(api, renderer, off_png, kW, kH, 2,
+             "hud-composite: unbound frames presented");
+    if (!cleared.empty()) {
+      check(std::memcmp(cleared.data(), off.data(), off.size()) == 0,
+            "hud-composite: unbind restores clear");
+    }
+  }
+
+  api->ui_destroy(ui);
+  api->renderer_destroy(renderer);
+  api->world_destroy(world);
+}
+
+}  // namespace
+
+auto main() -> int {
+  // Unbuffered stdout: on a segfault the CI log keeps every PASS line,
+  // pinpointing the crashing section (Windows gives no core dump).
+  setvbuf(stdout, nullptr, _IONBF, 0);
+  test_hud_composite();
+  std::printf(failures == 0 ? "HUD_COMPOSITE_OK\n"
+                            : "HUD_COMPOSITE_FAILURES=%d\n",
+              failures);
+  return failures == 0 ? 0 : 1;
+}