fix: use representative node metadata for nested container tabs

Replace container-tab fallback text (DockSplitPane/DockTabPane) with a summary derived from the representative DockNode title and icon (Title +N).

Keep container-tab headers reactive by updating on DockGraph revisions, nested tab selection changes, and DockNode title/icon changes.

Add DockLayoutEngine regression tests for representative summary rendering and selected-inner-tab synchronization, and update STATUS/DONE/ROADMAP/CHANGELOG to reflect 191 passing tests.

Author: Beowolve

CHANGELOG.md

@@ -10,7 +10,7 @@ The changelog is grouped by release tags (`vX.Y.Z`) and includes an `Unreleased`
 - ✅ Removed obsolete JavaFX test JVM module flags that caused classpath/module warning noise (`24ac0bc`).
 - ✅ Stabilized JavaFX module-path test runtime without FXML assumptions (`e8197a9`).
 - ✅ Migrated plugin/dependency versions to `gradle/libs.versions.toml` and reduced duplicated build configuration (`517b5db`).
-- ✅ Expanded shortcut, context-menu, and demo-accelerator coverage in unit tests; full suite now runs with 189 tests.
+- ✅ Expanded shortcut, context-menu, and demo-accelerator coverage in unit tests; full suite now runs with 191 tests.
 
 ### Framework and UI
 - ✅ Added configurable framework keyboard shortcut API in `SnapFX` (`setShortcut`, `clearShortcut`, `resetShortcutsToDefaults`, `getShortcuts`).
@@ -24,6 +24,7 @@ The changelog is grouped by release tags (`vX.Y.Z`) and includes an `Unreleased`
 - ✅ Reworked DockNode icon model to image-based rendering so each view creates its own icon node, preventing parent-sharing losses in floating title bars.
 - ✅ Floating title-bar icon now tracks active tab selection in floating tab layouts.
 - ✅ Hardened drop-zone edge-size clamping for tiny bounds so drag hover no longer throws `Math.clamp` min/max-order exceptions.
+- ✅ Tab headers for nested container layouts now use representative DockNode title/icon summaries (`Title +N`) instead of container class names.
 
 ### Documentation
 - ✅ Split repository workflow content out of `README.md` into dedicated `CONTRIBUTING.md` and `RELEASING.md` (`6f93d0a`).

DONE.md

@@ -59,7 +59,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ Full JPMS support with proper exports and opens
 - ✅ Compatible with Java 21 module system
 
-### Testing (12 test classes, 189 tests)
+### Testing (12 test classes, 191 tests)
 - ✅ `DockGraphTest` (56 tests) - Tree manipulation and algorithms
   - **+11 regression tests** for critical bug fixes
   - Tests for empty container prevention
@@ -70,7 +70,7 @@ SnapFX has been fully implemented with core functionality and is production-read
   - Edge case tests for null/no-op/detached-target handling
 - ✅ `DockLayoutSerializerTest` (9 tests) - Persistence functionality
   - **+1 regression test** for locked state synchronization (2026-02-10)
-- ✅ `DockLayoutEngineTest` (29 tests) - View creation with TestFX, context-menu interaction coverage, float-availability policy checks, and tiny-bounds drop-zone clamp regression coverage
+- ✅ `DockLayoutEngineTest` (31 tests) - View creation with TestFX, context-menu interaction coverage, representative container-tab title/icon behavior, float-availability policy checks, and tiny-bounds drop-zone clamp regression coverage
   - Memory cleanup tests for cache boundedness and undock/rebuild cycles
   - Layout optimization tests for empty/single-child roots
 - ✅ `SnapFXTest` (44 tests) - Hide/Restore + Floating Window API behavior plus configurable shortcut behavior
@@ -146,6 +146,7 @@ SnapFX has been fully implemented with core functionality and is production-read
 - ✅ **Property Bindings**: Reactive UI updates via JavaFX properties
 - ✅ **CSS Styling**: Native Modena theme integration
 - ✅ **Tab Overflow Dropdown**: Menu shows titles when using custom tab graphics
+- ✅ **Container tab summary headers**: Tabs hosting nested layouts now show representative DockNode title/icon with `+N` suffix instead of container class names
 - ✅ **Tab Auto-Hide**: In locked mode, tabs only visible when >1
 - ✅ **Close Button Options**: Toggle tab/title close buttons, keep tab close always visible, align styling, and hide the title bar when desired
 - ✅ **CSS-based Control Glyphs**: Dock/floating control icons are stylesheet-defined; title close glyph is aligned with tab close styling

ROADMAP.md

@@ -70,6 +70,7 @@ This roadmap lists planned work only; completed/fixed history is tracked in `CHA
 ### 1.5 UI Bug Fixes
 **Priority**: 🟡 High
 
+- ✅ **Container tab title/icon UX**: Tabs containing nested split/tab layouts now derive title/icon from a representative DockNode (`Title +N`) instead of showing container class names
 - 📋 No planned items; see `CHANGELOG.md` for completed fixes.
 
 ---

STATUS.md

@@ -5,7 +5,7 @@
 ## Build Status
 
 ✅ **Build**: `BUILD SUCCESSFUL`  
-✅ **Tests**: All 189 tests passing (latest full suite)
+✅ **Tests**: All 191 tests passing (latest full suite)
 ✅ **Module System**: Fully implemented (JPMS)  
 ✅ **Demo App**: Running successfully  
 ✅ **CI Automation**: GitHub Actions workflows added for push/PR tests and tag-triggered releases  
@@ -37,6 +37,7 @@
 - ✅ CSS styling (Modena theme)
 - ✅ Context menus for tab headers, dock-node headers, and split panes (with float-action availability policy support and close/float icon parity)
 - ✅ DockNode icons render as independent per-view image nodes (no shared-node icon loss across headers/tabs/floating title bars)
+- ✅ Container tabs now use representative DockNode title/icon summaries (`Title +N`) instead of internal container class names
 
 ### Drag & Drop (100% ✅)
 - ✅ DockDragService implementation
@@ -128,7 +129,7 @@
 ### Testing (100% ✅)
 - ✅ DockGraphTest (56 tests, +11 regression tests)
 - ✅ DockLayoutSerializerTest (9 tests, +1 regression test)
-- ✅ DockLayoutEngineTest (29 tests) - Includes tab/header/splitter context-menu coverage, float-availability policy checks, and tiny-bounds drop-zone clamp regression coverage
+- ✅ DockLayoutEngineTest (31 tests) - Includes tab/header/splitter context-menu coverage, representative container-tab title/icon behavior, float-availability policy checks, and tiny-bounds drop-zone clamp regression coverage
 - ✅ **SnapFXTest (44 tests)** - Hide/Restore + Floating Window API tests plus configurable shortcut behavior
 - ✅ DockGraphSplitTargetDockingTest (1 test)
 - ✅ DockDragServiceTest (8 tests) - D&D visibility, tab-hover activation, float-detach callback behavior, and ESC drag-cancel handling
@@ -138,7 +139,7 @@
 - ✅ SimpleExampleTest (2 tests) - Stylesheet resource resolution behavior
 - ✅ MarkdownDocumentationConsistencyTest (12 tests) - Markdown consistency guardrails
 - ✅ AboutDialogTest (2 tests) - About dialog branding resources and credit link targets
-- ✅ **189/189 tests passing** ✅
+- ✅ **191/191 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)

src/main/java/com/github/beowolve/snapfx/view/DockLayoutEngine.java

@@ -305,7 +305,8 @@ private void clearCacheForElement(DockElement element) {
 
     /**
      * Creates a Tab for the given DockElement. For DockNode, the tab header contains icon and title.
-     * For containers, a generic label is used. Handles drag & drop and close events.
+     * For containers, the tab label/icon is derived from the representative DockNode.
+     * Handles drag & drop and close events.
      * @param element The DockElement to represent as a Tab
      * @return The created Tab
      */
@@ -329,7 +330,10 @@ private Tab createTab(DockElement element, DockTabPane ownerTabPane) {
                 event.consume();
             });
         } else {
-            tab.setText(element.getClass().getSimpleName());
+            TabHeader tabHeader = createContainerTabHeader(tab, element);
+            tab.setGraphic(tabHeader.node());
+            tab.getProperties().put(TAB_CLEANUP_KEY, tabHeader.cleanup());
+            tab.getStyleClass().add("dock-tab-graphic");
             if (!shouldShowTabCloseButton()) {
                 tab.setClosable(false);
             } else {
@@ -344,6 +348,139 @@ private Tab createTab(DockElement element, DockTabPane ownerTabPane) {
         return tab;
     }
 
+    private TabHeader createContainerTabHeader(Tab tab, DockElement element) {
+        HBox tabHeader = new HBox(5);
+        tabHeader.setAlignment(Pos.CENTER_LEFT);
+
+        StackPane iconPane = new StackPane();
+        iconPane.setPrefSize(16, 16);
+        iconPane.setMaxSize(16, 16);
+        iconPane.setMinSize(16, 16);
+
+        Label tabLabel = new Label();
+        List<Runnable> subtreeCleanup = new ArrayList<>();
+
+        Runnable refreshHeader = () -> updateContainerTabHeader(tab, element, tabLabel, iconPane);
+        Runnable refreshListeners = () -> {
+            clearContainerTabHeaderListeners(subtreeCleanup);
+            registerContainerTabHeaderListeners(element, refreshHeader, subtreeCleanup);
+            refreshHeader.run();
+        };
+        ChangeListener<Number> revisionListener = (obs, oldValue, newValue) -> refreshListeners.run();
+        dockGraph.revisionProperty().addListener(revisionListener);
+        refreshListeners.run();
+
+        tabHeader.getChildren().addAll(iconPane, tabLabel);
+
+        Runnable cleanup = () -> {
+            dockGraph.revisionProperty().removeListener(revisionListener);
+            clearContainerTabHeaderListeners(subtreeCleanup);
+            iconPane.getChildren().clear();
+            iconPane.setVisible(true);
+            iconPane.setManaged(true);
+            tabLabel.setText("");
+        };
+        return new TabHeader(tabHeader, cleanup);
+    }
+
+    private void updateContainerTabHeader(Tab tab, DockElement element, Label tabLabel, StackPane iconPane) {
+        DockNode representativeNode = resolveRepresentativeNode(element);
+        int nodeCount = countDockNodes(element);
+        String title = buildRepresentativeTitle(representativeNode, nodeCount);
+        tab.setText(title);
+        tabLabel.setText(title);
+
+        iconPane.getChildren().clear();
+        if (representativeNode != null) {
+            ImageView icon = createDockNodeIcon(representativeNode.getIcon());
+            if (icon != null) {
+                iconPane.getChildren().add(icon);
+            }
+        }
+        boolean hasIcon = !iconPane.getChildren().isEmpty();
+        iconPane.setVisible(hasIcon);
+        iconPane.setManaged(hasIcon);
+    }
+
+    private void registerContainerTabHeaderListeners(DockElement element, Runnable onUpdate, List<Runnable> cleanup) {
+        if (element == null || onUpdate == null || cleanup == null) {
+            return;
+        }
+        if (element instanceof DockNode dockNode) {
+            ChangeListener<String> titleListener = (obs, oldValue, newValue) -> onUpdate.run();
+            ChangeListener<Image> iconListener = (obs, oldValue, newValue) -> onUpdate.run();
+            dockNode.titleProperty().addListener(titleListener);
+            dockNode.iconProperty().addListener(iconListener);
+            cleanup.add(() -> dockNode.titleProperty().removeListener(titleListener));
+            cleanup.add(() -> dockNode.iconProperty().removeListener(iconListener));
+        }
+        if (element instanceof DockTabPane tabPane) {
+            ChangeListener<Number> selectedIndexListener = (obs, oldValue, newValue) -> onUpdate.run();
+            tabPane.selectedIndexProperty().addListener(selectedIndexListener);
+            cleanup.add(() -> tabPane.selectedIndexProperty().removeListener(selectedIndexListener));
+        }
+        if (element instanceof DockContainer container) {
+            for (DockElement child : container.getChildren()) {
+                registerContainerTabHeaderListeners(child, onUpdate, cleanup);
+            }
+        }
+    }
+
+    private void clearContainerTabHeaderListeners(List<Runnable> cleanup) {
+        if (cleanup == null || cleanup.isEmpty()) {
+            return;
+        }
+        for (Runnable cleanupTask : new ArrayList<>(cleanup)) {
+            cleanupTask.run();
+        }
+        cleanup.clear();
+    }
+
+    private String buildRepresentativeTitle(DockNode representativeNode, int nodeCount) {
+        String baseTitle = representativeNode == null ? "Layout" : representativeNode.getTitle();
+        if (baseTitle == null || baseTitle.isBlank()) {
+            baseTitle = "Layout";
+        }
+        if (nodeCount <= 1) {
+            return baseTitle;
+        }
+        return baseTitle + " +" + (nodeCount - 1);
+    }
+
+    private DockNode resolveRepresentativeNode(DockElement element) {
+        if (element == null) {
+            return null;
+        }
+        if (element instanceof DockNode dockNode) {
+            return dockNode;
+        }
+        if (element instanceof DockTabPane tabPane && !tabPane.getChildren().isEmpty()) {
+            int selectedIndex = Math.clamp(tabPane.getSelectedIndex(), 0, tabPane.getChildren().size() - 1);
+            return resolveRepresentativeNode(tabPane.getChildren().get(selectedIndex));
+        }
+        if (element instanceof DockContainer container && !container.getChildren().isEmpty()) {
+            return resolveRepresentativeNode(container.getChildren().getFirst());
+        }
+        return null;
+    }
+
+    private int countDockNodes(DockElement element) {
+        if (element == null) {
+            return 0;
+        }
+        if (element instanceof DockNode) {
+            return 1;
+        }
+        if (element instanceof DockContainer container) {
+            int count = 0;
+            for (DockElement child : container.getChildren()) {
+                count += countDockNodes(child);
+            }
+            return count;
+        }
+        return 0;
+    }
+
     private ContextMenu createHeaderContextMenu(DockNode dockNode) {
         ContextMenu contextMenu = new ContextMenu();
 

src/test/java/com/github/beowolve/snapfx/view/DockLayoutEngineTest.java

@@ -18,6 +18,8 @@
 import javafx.scene.input.MouseButton;
 import javafx.scene.input.MouseEvent;
 import javafx.scene.input.PickResult;
+import javafx.scene.image.ImageView;
+import javafx.scene.image.WritableImage;
 import javafx.scene.layout.StackPane;
 import javafx.scene.layout.HBox;
 import javafx.scene.control.Tab;
@@ -126,6 +128,72 @@ void testDockNodeTabTextUsesTitle() {
         assertEquals("Renamed", tabPane.getTabs().get(0).getText());
     }
 
+    @Test
+    void testContainerTabUsesRepresentativeNodeTitleAndIconSummary() {
+        DockNode plainNode = new DockNode(new Label("Plain"), "Plain");
+        DockNode splitNode1 = new DockNode(new Label("Split 1"), "Split 1");
+        DockNode splitNode2 = new DockNode(new Label("Split 2"), "Split 2");
+        WritableImage splitIcon = new WritableImage(16, 16);
+        splitNode1.setIcon(splitIcon);
+        DockSplitPane splitPane = new DockSplitPane(Orientation.HORIZONTAL);
+        splitPane.addChild(splitNode1);
+        splitPane.addChild(splitNode2);
+
+        DockTabPane rootTabPane = new DockTabPane();
+        rootTabPane.addChild(plainNode);
+        rootTabPane.addChild(splitPane);
+        dockGraph.setRoot(rootTabPane);
+
+        TabPane tabPane = assertInstanceOf(TabPane.class, layoutEngine.buildSceneGraph());
+        Tab containerTab = tabPane.getTabs().get(1);
+
+        assertEquals("Split 1 +1", containerTab.getText());
+        assertNotEquals("DockSplitPane", containerTab.getText());
+
+        HBox header = assertInstanceOf(HBox.class, containerTab.getGraphic());
+        StackPane iconPane = assertInstanceOf(StackPane.class, header.getChildren().getFirst());
+        ImageView iconView = assertInstanceOf(ImageView.class, iconPane.getChildren().getFirst());
+        assertEquals(splitIcon, iconView.getImage());
+    }
+
+    @Test
+    void testContainerTabFollowsSelectedInnerTabForRepresentativeTitleAndIcon() {
+        DockNode plainNode = new DockNode(new Label("Plain"), "Plain");
+        DockNode innerNode1 = new DockNode(new Label("One"), "One");
+        DockNode innerNode2 = new DockNode(new Label("Two"), "Two");
+        DockNode splitSiblingNode = new DockNode(new Label("Split Sibling"), "Split Sibling");
+        WritableImage icon1 = new WritableImage(16, 16);
+        WritableImage icon2 = new WritableImage(16, 16);
+        innerNode1.setIcon(icon1);
+        innerNode2.setIcon(icon2);
+
+        DockTabPane innerTabPane = new DockTabPane();
+        innerTabPane.addChild(innerNode1);
+        innerTabPane.addChild(innerNode2);
+        innerTabPane.setSelectedIndex(0);
+
+        DockSplitPane splitPane = new DockSplitPane(Orientation.HORIZONTAL);
+        splitPane.addChild(innerTabPane);
+        splitPane.addChild(splitSiblingNode);
+
+        DockTabPane rootTabPane = new DockTabPane();
+        rootTabPane.addChild(plainNode);
+        rootTabPane.addChild(splitPane);
+        dockGraph.setRoot(rootTabPane);
+
+        TabPane tabPane = assertInstanceOf(TabPane.class, layoutEngine.buildSceneGraph());
+        Tab containerTab = tabPane.getTabs().get(1);
+        assertEquals("One +2", containerTab.getText());
+
+        innerTabPane.setSelectedIndex(1);
+        assertEquals("Two +2", containerTab.getText());
+
+        HBox header = assertInstanceOf(HBox.class, containerTab.getGraphic());
+        StackPane iconPane = assertInstanceOf(StackPane.class, header.getChildren().getFirst());
+        ImageView iconView = assertInstanceOf(ImageView.class, iconPane.getChildren().getFirst());
+        assertEquals(icon2, iconView.getImage());
+    }
+
     /**
      * Regression test: Tab close must use the same close handler as the title bar.
      * Bug: Closing a tab bypassed onNodeCloseRequest, so hidden nodes were not tracked.