XCEngine/docs/used/NewEditor_WorkspaceUtilityWindowSemanticSplitPlan_2026-04-22.md

NewEditor Workspace Utility Window Semantic Split Plan

Date: 2026-04-22 Status: Complete and Archived

0. Execution Progress

Completed on 2026-04-22

Phase A shell/content split foundation is now in place.

Completed changes:

1. EditorWindow no longer constructs itself from UIEditorWorkspaceController
2. EditorWindowRuntimeController no longer directly owns m_workspaceController
3. EditorWindowHostRuntime::CreateEditorWindow(...) no longer accepts raw workspace controller input
4. a new content abstraction now exists:
   • EditorWindowContentController
   • EditorWorkspaceWindowContentController
5. current workspace-backed behavior has been moved behind the new content layer without changing workspace semantics
6. detached workspace chrome policy now reads window-content capabilities instead of shell-owned workspace state
7. XCUIEditorApp Debug build passes after this phase

What is intentionally not done yet:

1. utility window domain does not exist yet
2. color picker still opens through detached panel workflow
3. toolWindow still exists in workspace panel descriptors as legacy leakage to remove in later phases

This means the root shell/content ownership boundary has been extracted first, while feature semantics remain unchanged for safety.

Completed on 2026-04-22

Phase C, Phase D, and Phase E implementation are now in place.

Completed changes:

1. a first-class utility window domain now exists:
   • EditorUtilityWindowKind
   • EditorWindowOpenUtilityWindowRequest
   • EditorUtilityWindowCoordinator
   • EditorUtilityWindowRegistry
2. color picker open intent no longer routes through detached workspace mutation
3. the color picker now opens through utility-window coordination and utility content
4. color picker has been removed from:
   • UIEditorPanelRegistry
   • shell hosted-panel composition
   • workspace detached-panel request plumbing
5. openDetachedPanel has been deleted from frame transfer routing
6. UIEditorWindowWorkspaceController::OpenPanelInNewWindow(...) has been deleted
7. toolWindow and related workspace utility inference have been deleted
8. detached floating-window placement logic is now shared instead of duplicated
9. XCUIEditorApp Debug build passes after this phase

Verified and Archived on 2026-04-22

Section 10 manual verification has now passed.

Verified outcomes:

1. workspace regression checks passed
2. utility window checks passed
3. cross-boundary checks passed
4. XCUIEditorApp Debug build passes
5. XCUIEditorApp Release build passes

1. Objective

This plan solves the problem from the architectural root, not by adding another special case.

The goal is to completely separate:

1. native window shell
2. workspace-backed dockable windows
3. utility windows that are inherently standalone

The immediate trigger is the color picker window, but the real issue is broader:

1. EditorWindow is still specialized around UIEditorWorkspaceController
2. utility windows are currently modeled as panels with a toolWindow flag
3. the color picker is opened through openDetachedPanel
4. utility window policy is inferred indirectly from workspace root content

This architecture is semantically wrong.

If a window is inherently standalone and can never merge back into the main workspace, it must not live inside the workspace panel model.

2. Architectural Judgment

The current implementation shares too much.

Sharing the native host is correct:

1. HWND lifetime
2. D3D render loop
3. DPI handling
4. input capture
5. title bar / chrome
6. screenshot and frame pacing

Sharing the workspace panel abstraction is not correct for the color picker.

The color picker is currently treated as:

1. a panel descriptor in UIEditorPanelRegistry
2. a hosted panel inside shell composition
3. a detached panel opened via OpenPanelInNewWindow(...)
4. a single-root detached workspace that is merely styled as a tool window

That means the color picker still belongs to the dock / detach / re-dock / transfer universe.

This is the wrong owner domain.

3. Confirmed Root Cause

The root cause is not one bad function.

The root cause is that the codebase currently conflates two different semantics:

1. workspace window
   • owns a UIEditorWorkspaceController
   • participates in layout, docking, tab stacks, cross-window transfer
   • can detach and re-merge
2. utility window
   • owns standalone tool content
   • does not belong to workspace layout
   • does not expose nodeId / panelId docking semantics
   • cannot merge into the main window

Today those two semantics are both forced through EditorWindow + UIEditorWorkspaceController.

That is why the color picker can only exist as a fake panel.

4. Current Coupling Points

These are the concrete places where the semantic mistake is encoded today:

1. new_editor/app/Platform/Win32/EditorWindow.h
   • EditorWindow constructor directly requires UIEditorWorkspaceController
2. new_editor/app/Platform/Win32/EditorWindowRuntimeController.h
   • runtime directly stores m_workspaceController
3. new_editor/app/Platform/Win32/EditorWindowTransferRequests.h
   • utility-open intent is modeled as EditorWindowOpenDetachedPanelRequest
4. new_editor/app/Platform/Win32/EditorWindowFrameOrchestrator.cpp
   • color picker open is converted into openDetachedPanel
5. new_editor/app/Platform/Win32/WindowManager/EditorWindowWorkspaceCoordinator.cpp
   • color picker window creation is routed through workspace mutation
6. new_editor/src/Workspace/UIEditorWindowWorkspaceController.cpp
   • OpenPanelInNewWindow(...) is used to create the color picker window
7. new_editor/include/XCEditor/Panels/UIEditorPanelRegistry.h
   • toolWindow is attached to panel descriptors
8. new_editor/src/Workspace/UIEditorDetachedWindowPolicy.cpp
   • utility semantics are inferred from detached workspace root content
9. new_editor/app/Composition/EditorShellAssetBuilder.cpp
   • color picker is registered as a panel
10. new_editor/app/Composition/EditorShellHostedPanelCoordinator.cpp
    • color picker lives inside hosted panel update / dispatch infrastructure
11. new_editor/app/State/EditorColorPickerToolState.h
    • color picker open intent is expressed as requestOpenDetachedPanel

This is not one bug. This is an ownership boundary failure.

5. Refactor Red Lines

The refactor must not degrade into any of the following:

1. keeping the color picker in UIEditorPanelRegistry and merely adding more if (panelId == "color-picker") branches
2. keeping toolWindow as the long-term mechanism for non-workspace windows
3. keeping openDetachedPanel as the generic request type for utility windows
4. allowing utility windows to remain inside UIEditorWindowWorkspaceSet
5. preserving nodeId / panelId transfer semantics for utility windows
6. building a second special-case bypass inside EditorWindowWorkspaceCoordinator
7. renaming the current path without changing ownership

If any of those remain in the end state, the architecture is still wrong.

6. Target End State

The correct end state has three layers.

6.1 Native Shell Layer

A shared native shell owns only platform and rendering responsibilities:

1. HWND creation and destruction
2. D3D renderer / swap chain / present loop
3. window chrome and title
4. DPI, sizing, screenshot, pointer capture plumbing
5. input event collection and dispatch to content

This layer must not know whether the content is workspace-backed or utility-backed.

Suggested shape:

1. EditorNativeWindowShell
2. EditorNativeWindowRuntime
3. IEditorWindowContentController

The names can change, but the boundary cannot.

6.2 Workspace Window Layer

Workspace windows are the only windows allowed to own:

1. UIEditorWorkspaceController
2. EditorShellRuntime
3. dock host interaction state
4. detached panel transfer requests
5. cross-window tab drag and dock / re-dock semantics

A workspace window can:

1. represent the main window
2. represent a detached panel window
3. merge back into another workspace window

Suggested shape:

1. EditorWorkspaceWindowContent
2. EditorWorkspaceWindowCoordinator
3. EditorWorkspaceWindowTransferRequests

6.3 Utility Window Layer

Utility windows are standalone tool surfaces.

They must not own:

1. UIEditorWorkspaceController
2. dock layout
3. tab stack state
4. nodeId
5. panelId workspace transfer semantics

They may own:

1. dedicated tool state
2. dedicated rendering and input logic
3. explicit request / response channels to editor features
4. separate focus / reuse / close rules

Suggested shape:

1. EditorUtilityWindowContent
2. EditorUtilityWindowCoordinator
3. EditorOpenUtilityWindowRequest
4. EditorUtilityWindowKind
5. EditorColorPickerUtilityWindowContent

7. Required Ownership Changes

The refactor must move ownership, not just code location.

7.1 Window Identity

Today:

1. detached color picker window identity is derived from panelId
2. detached utility behavior is inferred from the root workspace panel descriptor

After refactor:

1. workspace windows are identified inside workspace domain
2. utility windows are identified inside utility domain
3. utility window identity is no longer a panel identity

7.2 Open Intent

Today:

1. color picker open intent means "open this panel in a detached window"

After refactor:

1. color picker open intent means "open or focus utility window of kind color picker"
2. the request carries explicit tool payload:
   • initial color
   • alpha mode
   • inspector target binding
   • focus / reuse policy

7.3 Persistence

Today:

1. utility-like windows still pass through workspace layout concepts

After refactor:

1. workspace window state remains in workspace layout persistence
2. utility window state uses separate persistence or no persistence
3. utility windows never enter UIEditorWindowWorkspaceSet

7.4 Visual Policy

Today:

1. tool-window policy is inferred from detached workspace content

After refactor:

1. workspace detached-window policy is only about workspace windows
2. utility-window policy belongs to utility window descriptors or utility content

8. Migration Strategy

The migration must happen in strict phases.

Phase A. Extract a Content-Neutral Native Window Shell

Goal:

1. stop making the native window host depend directly on UIEditorWorkspaceController

Required changes:

1. split the current EditorWindow responsibilities into:
   • shell responsibilities
   • content responsibilities
2. extract a content interface for:
   • update
   • draw
   • input dispatch
   • external preview / title contributions if needed
3. make EditorWindowHostRuntime::CreateEditorWindow(...) create a shell plus content, not a workspace-bound window object

Success criteria:

1. a shell instance can host workspace content
2. a shell instance can host non-workspace content
3. no shell constructor directly requires UIEditorWorkspaceController

Red line:

1. do not keep a hidden m_workspaceController in shell-level runtime

Phase B. Move Existing Workspace Windows onto the New Content Layer

Goal:

1. preserve all existing main-window and detached-panel behavior while isolating it into workspace-specific content

Required changes:

1. create EditorWorkspaceWindowContent
2. move current workspace-only responsibilities into it:
   • UIEditorWorkspaceController
   • EditorShellRuntime
   • workspace frame orchestration
   • dock transfer request generation
3. keep EditorWindowWorkspaceCoordinator but narrow its responsibility to workspace windows only

Success criteria:

1. main window still works
2. detached panel windows still work
3. cross-window tab drag and re-dock still work
4. utility windows are still not introduced yet, but the shell is already ready for them

Phase C. Introduce a Real Utility Window Domain

Goal:

1. create a first-class utility window pipeline independent from workspace mutation

Required changes:

1. add utility window request types
2. add EditorUtilityWindowCoordinator
3. add utility window registry / descriptor model
4. define utility window lifecycle:
   • open
   • reuse
   • focus
   • close
   • app-shutdown behavior
5. define utility window payload passing

Success criteria:

1. utility windows can be created without touching UIEditorWindowWorkspaceController
2. utility windows can be reused without entering workspace state
3. utility windows do not generate dock transfer requests

Phase D. Migrate Color Picker Out of the Panel System

Goal:

1. make the color picker the first true utility window

Required changes:

1. remove color picker from UIEditorPanelRegistry
2. remove color picker from shell hosted-panel composition
3. replace requestOpenDetachedPanel with utility-window open intent
4. implement EditorColorPickerUtilityWindowContent
5. wire inspector -> color picker communication through explicit tool contracts instead of workspace panel visibility

Success criteria:

1. opening the color picker never calls OpenPanelInNewWindow(...)
2. color picker never appears in workspace visible panels
3. color picker never participates in detach / re-dock / cross-window panel transfer
4. color picker still updates inspector-bound color correctly

Phase E. Delete Transitional Workspace Utility Leakage

Goal:

1. remove all leftover semantic leakage after color picker migration

Required deletions:

1. remove toolWindow from UIEditorPanelDescriptor
2. remove color-picker-specific detached-panel request plumbing
3. remove utility inference from UIEditorDetachedWindowPolicy
4. remove any remaining workspace special cases that exist only for the old color picker path

Success criteria:

1. workspace code no longer knows the color picker exists
2. utility code no longer depends on panel registry membership
3. no root-content-based inference is needed to determine window kind

9. Files Expected to Change

This refactor is architecture-level and will necessarily touch a broad slice.

Shell / Host Layer

1. new_editor/app/Platform/Win32/EditorWindow.h
2. new_editor/app/Platform/Win32/EditorWindow.cpp
3. new_editor/app/Platform/Win32/EditorWindowRuntimeController.h
4. new_editor/app/Platform/Win32/EditorWindowRuntimeController.cpp
5. new_editor/app/Platform/Win32/WindowManager/EditorWindowHostRuntime.h
6. new_editor/app/Platform/Win32/WindowManager/EditorWindowHostRuntime.cpp
7. new_editor/app/Platform/Win32/WindowManager/EditorWindowManager.cpp
8. new_editor/app/Platform/Win32/WindowManager/EditorWindowMessageDispatcher.cpp

Workspace Layer

1. new_editor/app/Platform/Win32/WindowManager/EditorWindowWorkspaceCoordinator.h
2. new_editor/app/Platform/Win32/WindowManager/EditorWindowWorkspaceCoordinator.cpp
3. new_editor/app/Platform/Win32/EditorWindowFrameOrchestrator.cpp
4. new_editor/app/Platform/Win32/EditorWindowTransferRequests.h
5. new_editor/src/Workspace/UIEditorWindowWorkspaceController.cpp
6. new_editor/src/Workspace/UIEditorDetachedWindowPolicy.cpp

Utility Layer

1. new utility window coordinator files
2. new utility window descriptor / request files
3. new color picker utility content files
4. possibly a host-level coordinator that routes shell instances to workspace or utility content

Color Picker / Feature Layer

1. new_editor/app/State/EditorColorPickerToolState.h
2. new_editor/app/State/EditorColorPickerToolState.cpp
3. new_editor/app/Features/ColorPicker/ColorPickerPanel.h
4. new_editor/app/Features/ColorPicker/ColorPickerPanel.cpp
5. new_editor/app/Composition/EditorShellAssetBuilder.cpp
6. new_editor/app/Composition/EditorShellHostedPanelCoordinator.cpp
7. new_editor/app/Composition/EditorShellRuntime.h
8. new_editor/app/Composition/EditorShellRuntime.cpp
9. new_editor/app/Composition/EditorShellDrawComposer.cpp

10. Verification Matrix

This refactor is not done unless all of the following are checked.

Workspace Regression Checks

1. main window render / input / title behavior is intact
2. panel detach still creates detached workspace windows
3. detached workspace windows can re-dock
4. cross-window tab drag-drop still works
5. workspace close path still closes detached workspace windows correctly
6. workspace layout persistence still excludes utility windows

Utility Window Checks

1. opening color picker creates or focuses a utility window, not a detached panel window
2. color picker cannot be docked into the main window
3. color picker cannot be merged by tab drag
4. color picker does not appear in workspace visible-panel lists
5. color picker close does not mutate workspace layout
6. color picker reuse policy is correct:
   • single-instance reuse or explicit multi-instance rule, but not accidental workspace reuse

Cross-Boundary Checks

1. inspector -> color picker color synchronization still works
2. closing the main app tears down utility windows correctly
3. focus changes between workspace and utility windows do not break input capture
4. utility windows do not accidentally receive workspace drop preview / transfer state

Build Checks

1. XCUIEditorApp Debug build passes
2. XCUIEditorApp Release build passes if used by the team

11. Completion Criteria

This refactor is complete only when all of these are true:

1. no utility window is represented as a workspace panel
2. EditorWindow shell no longer requires UIEditorWorkspaceController
3. workspace and utility windows share only native shell infrastructure
4. toolWindow is not the long-term carrier of utility-window semantics
5. the color picker opens through utility window coordination, not workspace mutation
6. workspace code can be reasoned about without referencing utility windows
7. utility windows can be reasoned about without referencing dock / transfer semantics

12. Final Statement

The correct fix is not:

1. a new bypass for the color picker
2. another flag on panel descriptors
3. another branch inside workspace mutation

The correct fix is to restore the missing architectural boundary:

1. native shell is shared
2. workspace semantics are isolated
3. utility semantics are isolated

Only after this split is in place will the color picker stop being a fake detached panel and become a real standalone editor window type.