fix: repair DockDebugOverlay HUD layout and drag diagnostics

Restore DockDebugOverlay as a managed pref-sized overlay panel so the HUD background renders correctly and the panel is no longer clipped in the top-left corner when mounted as a StackPane overlay.

Refresh HUD text from the active drag service while attached to a scene so target/zone diagnostics follow in-place DockDragData mutations instead of remaining stuck at
one, and show dock-node titles for DockNode targets.

Keep the MainDemo HUD as a local debug-toggle option (no default-on requirement), add DockDebugOverlay regression coverage for layout/diagnostics behavior, and update status/roadmap/done/changelog docs plus current test counts.

Author: Beowolve

CHANGELOG.md

@@ -6,6 +6,17 @@ The changelog is grouped by release tags (`vX.Y.Z`) and includes an `Unreleased`
 
 ## Unreleased
 
+### Build and Test
+- ✅ Added `DockDebugOverlayTest` coverage for HUD layout defaults (managed pref-sized panel + background presence) and live target/zone diagnostics refresh when drag data mutates in place.
+
+### Framework and UI
+- ✅ Fixed `DockDebugOverlay` HUD rendering and diagnostics behavior used by MainDemo debugging: the HUD panel now lays out correctly with visible background (no top-left clipping), and target/zone text updates live during active drags instead of staying at `none`.
+- ✅ Improved `DockDebugOverlay` target diagnostics text to show the dragged hover target dock-node title for `DockNode` targets (instead of the generic `DockNode` type label).
+- ✅ Kept the MainDemo `DockDebugOverlay` HUD as a local debug-toggle option after the overlay fixes (no default-on requirement).
+
+### Documentation
+- ✅ Updated roadmap/status/done docs to mark the `DockDebugOverlay` HUD fixes follow-up as completed (while noting the MainDemo HUD remains opt-in) and return current priority focus to the Phase 3 UX backlog.
+
 ## v0.4.0 - 2026-02-25
 
 ### Build and Test

DONE.md

@@ -88,7 +88,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ `EditorCloseDecisionPolicyTest` (5 tests) - Deterministic close-decision behavior for dirty editor nodes
 - ✅ `MarkdownDocumentationConsistencyTest` (12 tests) - Documentation consistency guardrails
 - ✅ CI flake guard for critical interaction suites (`SnapFXTest`, `DockFloatingWindowTest`, `DockDragServiceTest`) runs 3x per CI execution
-- ✅ All tests passing (313/313) ✅
+- ✅ All tests passing (314/314) ✅
 - ✅ **Testing Policy** established (TESTING_POLICY.md)
 - ✅ Mandatory regression tests for all bug fixes
 
@@ -181,6 +181,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ **Framework sidebar visual baseline**: SnapFX now renders left/right sidebar icon strips with immediate title tooltips, click-to-open overlay panels, same-icon toggle close, outside-click overlay close, and pin/unpin switching to layout-consuming side panels
 - ✅ **MainDemo framework-sidebar validation path**: MainDemo now uses the framework-rendered sidebar UI again (instead of the temporary demo-only strip wrapper) for Phase-C manual testing
 - ✅ **MainDemo D&D debug HUD temporary disable**: `DockDebugOverlay` HUD overlay is temporarily disabled in MainDemo until sidebar interaction work is completed; a post-sidebar fix/re-enable follow-up is tracked for background/clipping/data-text issues
+- ✅ **DockDebugOverlay HUD fixes**: `DockDebugOverlay` now renders as a managed pref-sized HUD panel again (background and top-left clipping fixed), refreshes live target/zone diagnostics during drag even when `DockDragData` mutates in place, and shows dock-node target titles in the HUD; MainDemo keeps the HUD behind a local debug toggle
 - ✅ **Phase-C sidebar interaction polish fixes**: Pinning now starts collapsed by default, overlay hit-testing no longer blocks sidebar interactions, and right-side unpin keeps overlay panels on the correct side
 - ✅ **Pinned active-icon collapse policy option**: SnapFX now exposes a configurable policy for clicking the active icon of a pinned-open sidebar panel (default collapses), and MainDemo exposes the toggle in Settings for manual UX validation
 - ✅ **Pinned active-icon collapse pin-preservation fix**: Collapsing a pinned-open sidebar panel via active icon now keeps the sidebar in pinned mode and reopens pinned on the next icon click
@@ -318,7 +319,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 
 See [ROADMAP.md](ROADMAP.md) for planned features and improvements.
 
-**Current Priority**: Sidebar interaction parity (Phase 2, current scope) is complete; next focus is the `DockDebugOverlay` HUD fix/re-enable follow-up, then return to the Phase 3 user-experience backlog.
+**Current Priority**: Sidebar interaction parity (Phase 2, current scope) and the `DockDebugOverlay` HUD follow-up are complete; next focus returns to the Phase 3 user-experience backlog.
 
 ---
 

ROADMAP.md

@@ -45,7 +45,7 @@ This roadmap lists planned work only; completed/fixed history is tracked in `CHA
 ### 1.2 Debug & Monitoring
 **Priority**: 🟡 High
 
-- 📋 **DockDebugOverlay HUD fix + re-enable (after sidebar Phase 2)**: Re-enable the temporary MainDemo D&D HUD after fixing missing background rendering, top-left clipping, and incorrect `none` values for target/zone text during active drags
+- ✅ **DockDebugOverlay HUD fixes**: Fixed missing panel background rendering (layout sizing), top-left clipping, and stale `none` target/zone diagnostics text during active drags; MainDemo HUD remains a local debug-toggle option
 - ✅ **MainDemo debug/settings split divider stability**: The outer demo split divider between the dock area and Debug/Settings tabs now remains stable during dock-layout rebuilds by updating a persistent left-side host container instead of replacing the split item
 
 ### 1.3 Testing & Quality Assurance  

STATUS.md

@@ -154,12 +154,13 @@
 - ✅ DockDragServiceTest (8 tests) - D&D visibility, tab-hover activation, float-detach callback behavior, and ESC drag-cancel handling
 - ✅ DockFloatingWindowTest (31 tests) - Floating title bar controls, context menu behavior (attach/pin icons + attach action), floating-header sidebar move-menu callback forwarding, pin behavior, icon rendering/sync regression coverage, single-node float-menu policy, maximize/restore interaction behavior, scene-level drag continuity (including release/reset and non-primary guard behavior), resize-min constraints, interactive-target cursor reliability, and floating/main edge snapping behavior (including overlap-guard, adjacent-edge cases, and main-window shadow-inset compensation)
 - ✅ DockFloatingSnapEngineTest (6 tests) - Snap candidate scoring, overlap-aware candidate generation, and shadow-inset compensation behavior
-- ✅ MainDemoTest (24 tests) - Demo app icon resource wiring, menu icon behavior, sidebar menu/list helper coverage for Phase-C manual controls, sidebar settings width-control API-parity wiring (including `DockSideBarMode` settings control), debug/settings outer-split divider-stability regression coverage, demo shortcut wiring, floating snap-target settings resolution coverage, load-error message formatting, owner-aware error-alert behavior, FileChooser helper coverage for shared layout/editor chooser configuration, and named theme-catalog/resource coverage
+- ✅ DockDebugOverlayTest (2 tests) - HUD layout-state defaults (managed + pref-sized panel background) and live diagnostics refresh coverage for mutated drag-state updates (`Target`/`Zone` no longer stuck at `none`)
+- ✅ MainDemoTest (23 tests) - Demo app icon resource wiring, menu icon behavior, sidebar menu/list helper coverage for Phase-C manual controls, sidebar settings width-control API-parity wiring (including `DockSideBarMode` settings control), debug/settings outer-split divider-stability regression coverage, demo shortcut wiring, floating snap-target settings resolution coverage, load-error message formatting, owner-aware error-alert behavior, FileChooser helper coverage for shared layout/editor chooser configuration, and named theme-catalog/resource coverage
 - ✅ DemoNodeFactoryTest (3 tests) - Unknown-node fallback strategy coverage (framework placeholder vs. custom demo fallback node) plus SnapFX integration coverage for unsupported-type recovery with the default demo factory
 - ✅ EditorCloseDecisionPolicyTest (5 tests) - Deterministic close-decision policy checks
 - ✅ MarkdownDocumentationConsistencyTest (12 tests) - Markdown consistency guardrails
 - ✅ AboutDialogTest (2 tests) - About dialog branding resources and credit link targets
-- ✅ **313/313 tests passing** ✅
+- ✅ **314/314 tests passing** ✅
 - ✅ **Performance tests for large layouts** (50+ nodes with stress move/cleanup operations)
 - ✅ **Memory leak cleanup tests** (cache boundedness, undock cleanup, large-layout detach/attach cycles)
 - ✅ **Edge case tests** (null inputs, detached nodes, invalid move targets, no-op revision checks)
@@ -180,6 +181,7 @@
 - ✅ About dialog extracted into dedicated class with dynamic version info, large logo branding, and icon credits
 - ✅ About dialog easter egg animation (triple-click logo)
 - ✅ Debug view toggle
+- ✅ DockDebugOverlay HUD issues are fixed after sidebar Phase 2 (panel layout/background rendering, top-left clipping, and live target/zone diagnostics updates during drag); MainDemo keeps the HUD behind a local debug toggle
 - ✅ Settings tab for live layout options (title bar, close buttons, drop visualization, lock, floating pin controls, floating-window snapping controls, and Phase-C pinned side-bar manual test controls for pin/restore/pin-open)
 - ✅ File workflows now use shared `FileChooser` helpers for layout open/save and editor open/save-as to keep extension filters and defaults consistent
 - ✅ Settings tab now includes a theme selector driven by the SnapFX named theme catalog (`Light`, `Dark`) and applies styles via runtime API
@@ -218,13 +220,12 @@
 - ⚠️ Memory: Automated heap profiling in CI not implemented
 - ⚠️ UI: Global interaction animations missing (only About dialog easter egg animation exists; tracked in `ROADMAP.md` Phase 3.3)
 - ⚠️ UI: Context-menu extensibility API for custom menu items is not implemented yet (tracked in `ROADMAP.md` Phase 3.2)
-- ⚠️ UI: `DockDebugOverlay` HUD in MainDemo is temporarily disabled; sidebar Phase 2 is complete and the next follow-up is the tracked HUD fix/re-enable in `ROADMAP.md` Phase 1.2 (background rendering, top-left clipping, and `none` diagnostics text)
 
 ## Next Steps
 
 See [ROADMAP.md](ROADMAP.md) for detailed future development plans.
 
-**Priority**: Sidebar Phase 2 interaction parity is complete for the current scope; next focus is the `DockDebugOverlay` HUD fix/re-enable follow-up, then return to the broader Phase 3 UX backlog.
+**Priority**: Sidebar Phase 2 interaction parity and the `DockDebugOverlay` HUD follow-up are complete for the current scope; next focus returns to the broader Phase 3 UX backlog (context-menu extensibility API and global interaction animation polish).
 
 ---
 

src/main/java/com/github/beowolve/snapfx/debug/DockDebugOverlay.java

@@ -1,13 +1,15 @@
 package com.github.beowolve.snapfx.debug;
 
+import com.github.beowolve.snapfx.model.DockNode;
+import com.github.beowolve.snapfx.theme.DockThemeStyleClasses;
 import com.github.beowolve.snapfx.dnd.DockDragData;
 import com.github.beowolve.snapfx.dnd.DockDragService;
 import com.github.beowolve.snapfx.model.DockElement;
 import com.github.beowolve.snapfx.model.DockGraph;
 import com.github.beowolve.snapfx.model.DockPosition;
-import javafx.beans.property.ObjectProperty;
-import javafx.beans.property.SimpleObjectProperty;
+import javafx.animation.AnimationTimer;
 import javafx.geometry.Insets;
+import javafx.scene.layout.Region;
 import javafx.scene.layout.*;
 import javafx.scene.paint.Color;
 import javafx.scene.text.Text;
@@ -18,24 +20,26 @@
  * Lightweight debug overlay that renders the current D&D state as a small HUD.
  */
 public class DockDebugOverlay extends StackPane {
-    private final ObjectProperty<DockDragData> currentDrag;
+    private final DockDragService dragService;
+    private final AnimationTimer refreshTimer;
 
     private final Text hudText;
+    private String lastRenderedText;
+    private boolean lastVisible;
 
     public DockDebugOverlay(DockGraph dockGraph, DockDragService dragService) {
         Objects.requireNonNull(dockGraph, "dockGraph");
-        Objects.requireNonNull(dragService, "dragService");
-
-        this.currentDrag = new SimpleObjectProperty<>(dragService.currentDragProperty().get());
+        this.dragService = Objects.requireNonNull(dragService, "dragService");
 
         setMouseTransparent(true);
-        setManaged(false);
         setPickOnBounds(false);
-
+        setMaxSize(Region.USE_PREF_SIZE, Region.USE_PREF_SIZE);
         setPadding(new Insets(8));
+        setVisible(false);
+        getStyleClass().add(DockThemeStyleClasses.DOCK_DEBUG_PANEL);
 
         hudText = new Text();
-        hudText.setFill(Color.WHITE);
+        hudText.setFill(Color.RED);
 
         var bg = new Background(new BackgroundFill(Color.rgb(0, 0, 0, 0.55), new CornerRadii(6), Insets.EMPTY));
         setBackground(bg);
@@ -44,28 +48,65 @@ public DockDebugOverlay(DockGraph dockGraph, DockDragService dragService) {
         StackPane.setMargin(hudText, new Insets(8));
 
         dragService.currentDragProperty().addListener((obs, old, cur) -> {
-            currentDrag.set(cur);
-            updateText(cur);
+            refreshFromDragService();
+        });
+
+        refreshTimer = new AnimationTimer() {
+            @Override
+            public void handle(long now) {
+                refreshFromDragService();
+            }
+        };
+        sceneProperty().addListener((obs, oldScene, newScene) -> {
+            if (newScene == null) {
+                refreshTimer.stop();
+            } else {
+                refreshTimer.start();
+                refreshFromDragService();
+            }
         });
 
-        updateText(currentDrag.get());
+        refreshFromDragService();
+    }
+
+    void refreshFromDragService() {
+        updateText(dragService.getCurrentDrag());
+    }
+
+    String getHudTextForTest() {
+        return hudText.getText();
     }
 
     private void updateText(DockDragData data) {
         if (data == null) {
-            setVisible(false);
+            applyHudState(false, null);
             return;
         }
 
-        setVisible(true);
-
         DockElement target = data.getDropTarget();
         DockPosition pos = data.getDropPosition();
 
         String targetText = target == null ? "none" : target.getClass().getSimpleName();
         String posText = pos == null ? "none" : pos.name();
 
-        hudText.setText("Drag: " + safeTitle(data) + "\nTarget: " + targetText + "\nZone: " + posText);
+        if (target instanceof DockNode dockNode) {
+            targetText = dockNode.getTitle();
+        }
+
+        applyHudState(
+            true,
+            "Drag: " + safeTitle(data) + "\nTarget: " + targetText + "\nZone: " + posText
+        );
+    }
+
+    private void applyHudState(boolean visible, String text) {
+        if (lastVisible == visible && Objects.equals(lastRenderedText, text)) {
+            return;
+        }
+        lastVisible = visible;
+        lastRenderedText = text;
+        setVisible(visible);
+        hudText.setText(text);
     }
 
     private String safeTitle(DockDragData data) {

src/main/java/com/github/beowolve/snapfx/demo/MainDemo.java

@@ -1021,8 +1021,7 @@ private void installDebugPanel() {
         mainSplit.setDividerPositions(0.72);
 
         if (ENABLE_DOCK_DEBUG_HUD) {
-            // Temporary local demo HUD for D&D diagnostics. Disabled while sidebar interaction work is in progress
-            // and until DockDebugOverlay issues (background/clipping/data text) are fixed.
+            // Local demo HUD for D&D diagnostics.
             DockDebugOverlay hud = new DockDebugOverlay(snapFX.getDockGraph(), snapFX.getDragService());
             StackPane stack = new StackPane(mainSplit, hud);
             StackPane.setAlignment(hud, Pos.TOP_LEFT);