UsdLayerManager/openspec/changes/archive/2026-05-08-make-imgui-widget-dockable/specs/imgui-docking/spec.md

ADDED Requirements

Requirement: Docking is enabled at compile time

The build system SHALL define IMGUI_HAS_DOCK prior to compiling any translation unit that includes imgui.h.

Scenario: ImGui compiled with docking support

• WHEN the project is compiled with CMake
• THEN IMGUI_HAS_DOCK is defined for all imgui source files and any file including imgui.h

Requirement: Docking is enabled at runtime

The application SHALL set ImGuiConfigFlags_DockingEnable in the ImGui IO configuration during initialization.

Scenario: Docking flag set on startup

• WHEN the application starts and ImGuiContext::Initialize() is called
• THEN io.ConfigFlags includes ImGuiConfigFlags_DockingEnable

Requirement: Main dockspace spans the application window

The application SHALL create a full-viewport dockspace via ImGui::DockSpaceOverViewport() at the start of each frame's UI rendering.

Scenario: Dockspace created each frame

• WHEN Application::RenderUI() executes
• THEN ImGui::DockSpaceOverViewport() is called after NewFrame() and before any panel Begin/End calls

Scenario: Dockspace fills the entire viewport

• WHEN the application window is resized
• THEN the dockspace automatically fills the new window dimensions

Requirement: All panels are dockable

All application panels SHALL be created as dockable ImGui windows that integrate with the dockspace.

Scenario: Panel windows use standard Begin/End

• WHEN any panel window is rendered
• THEN its ImGui::Begin() call does not include SetNextWindowPos or SetNextWindowSize calls
• AND the window can be dragged, docked, tabbed, or floated by the user

Scenario: Core panels cannot be collapsed

• WHEN the Scene Hierarchy, Layer Panel, Viewport, or Property Panel windows are rendered
• THEN each window is created with ImGuiWindowFlags_NoCollapse

Requirement: Window visibility toggles persist

Existing View menu toggles for Stage Info and Demo Window SHALL continue to control window visibility.

Scenario: Toggle Stage Info visibility

• WHEN the user clicks "Stage Info" in the View menu
• THEN the Stage Info window appears or disappears
• AND the toggle state is reflected by the checkmark in the menu item

Scenario: Toggle Demo Window visibility

• WHEN the user clicks "ImGui Demo" in the View menu
• THEN the ImGui Demo Window appears or disappears
• AND the toggle state is reflected by the checkmark in the menu item

Requirement: Dock layout persists across sessions

The docking layout SHALL be saved to and restored from imgui.ini automatically by ImGui's built-in persistence.

Scenario: Layout restored on restart

• WHEN the user arranges panels into a custom docking layout and restarts the application
• THEN the previous docking layout is restored