XCEngine/docs/plan/editor-core-refactor-plan.md

Editor Core Refactor Plan

Goal

This refactor turns the current editor/app directory map from a documented convention into a build-checked architecture.

The desired production shape is:

XCUIEditor
  reusable editor UI framework:
  widgets, docking, shell, workspace, menu, viewport slots, field controls

XCEditorCore
  editor product core:
  composition, commands, state, project and scene services, feature panels,
  window/workspace core, and host-facing contracts

XCEditor
  thin executable host:
  main, Win32 process/window host, D3D12 runtime host, resources, startup,
  final object wiring

XCEditor may keep the output name XCEngine.exe; the target name should remain XCEditor.

Current Problem

The reusable layer is mostly healthy:

• editor/include/XCEditor/** and editor/src/** form XCUIEditor.
• XCUIEditor is testable and mostly free of app, Win32, and D3D12 concerns.

The app layer has a good directory vocabulary but enforcement is still incomplete:

• XCEditorCore now limits its public app include surface to editor/app/Core, editor/app/Commands, editor/app/State, and editor/app/Host/Interfaces, and app/core sources now include through explicit module roots instead of a private editor/app compatibility root. Concrete host code has converged under editor/app/Host/Win32 and editor/app/Host/D3D12.
• Feature panels no longer use Composition/EditorContext.h directly. The app-core and app feature/viewport test targets now exercise XCEditorCore outside the executable host.

Completed boundary cuts:

• Project service ownership has moved to editor/app/Services/Project. EditorProjectRuntime depends on the service-owned ProjectBrowserModel, and Features/Project/ProjectPanel owns the widget-tree projection.
• Panel IDs live under editor/app/Core/Panels, and workspace panel runtime contracts live under editor/app/Core/WorkspacePanels.
• Shared window category, lifecycle, chrome-policy, and native-host-policy contracts live under editor/app/Core/Windowing.
• Utility-window kinds, descriptors, and panel contracts live under editor/app/Core/UtilityWindows; concrete Color Picker/Add Component panel creation lives under editor/app/Features/EditorUtilityWindowRegistry.* and is injected from Application.
• Panel-facing app services live under editor/app/Core/Panels/EditorPanelServices.h. Workspace-panel and utility-window runtime contracts accept this service view instead of EditorContext, so concrete feature panels no longer depend on Composition/EditorContext.h.
• Win32 now hands render startup a neutral Rendering::Host::EditorWindowRenderRuntimeSurface value, and D3D12 no longer includes Platform/Win32/** editor surface headers to obtain HWND.
• Neutral host-facing contracts now live under editor/app/Host/Interfaces, including editor window host interfaces, render-runtime contracts, texture/viewport host contracts, pointer-capture contracts, and system interaction service interfaces.
• Concrete Win32 and D3D12 host implementations now live under editor/app/Host/Win32 and editor/app/Host/D3D12.
• Shared window screen geometry, chrome metrics, and frame transfer requests now live under editor/app/Core/Windowing, and XCEditorCore no longer exports the whole editor/app root as a public include directory.
• The private editor/app compatibility include root is gone from XCEditorCore and XCEditor. App implementation files now include through explicit module roots such as app/Composition, app/Features, app/Windowing, app/Rendering, app/Scene, app/Services, app/Support, app/Bootstrap, app/Host/Interfaces, app/Host/Win32, and app/Host/D3D12.
• editor_app_core_tests now links XCEditorCore directly and uses explicit app module include roots. Its initial suite covers host command routing, project runtime, shell asset validation, project browser model, hierarchy scene binding, and inspector presentation.
• editor_app_feature_tests now links XCEditorCore directly and uses explicit app module include roots. It restores project panel, scene viewport, viewport render-plan, viewport object-id picker, and app input-routing tests without widening the include surface.
• The old Win32 tab-drag-drop target test now covers the current reusable XCEditor/Docking/UIEditorDockHostTransfer.h API through editor_windowing_phase1_tests.

The root issue is not the existence of a single executable target by itself. The root issue was that shared app contracts were stored inside concrete layer directories, and CMake exposed the whole editor/app include root through XCEditorCore usage requirements. The public include surface has now been narrowed, and internal source compatibility with the private app root has now been removed. App-core and app feature/viewport tests now exercise the narrowed surface without using the whole editor/app include root.

Target Directory Shape

The refactor should converge on this shape:

editor/app/
  Core/
    Commands/
    Panels/
    State/
    UtilityWindows/
    Windowing/
    WorkspacePanels/

  Services/
    Project/
    Scene/

  Features/
    Console/
    ColorPicker/
    Hierarchy/
    Inspector/
    Project/
    Scene/

  Windowing/
    Content/
    Coordinator/
    Frame/
    Host/
    Runtime/

  Host/
    Interfaces/
    Win32/
    D3D12/

  Bootstrap/
  Support/

This is a convergence target, not a requirement to move every file at once. The first cut should only move contracts that are already acting as global app interfaces.

Dependency Rules

The final direction should be:

XCEditor -> XCEditorCore -> XCUIEditor -> XCEngine

Within XCEditorCore:

• Composition may depend on Core, Services, Windowing contracts, and XCUIEditor.
• Composition must not include concrete feature panel headers.
• Features may depend on Core, Services, and XCUIEditor.
• Services must not depend on Features.
• State must not depend on Composition.
• Windowing may depend on Core, Composition interfaces, and XCUIEditor, but must not include Win32 or D3D12 concrete host headers.
• Host contracts may live in Core or Host/Interfaces.
• Win32 and D3D12 concrete implementations live outside XCEditorCore unless they are purely abstract host contracts.

Phase 1: Fix Shared Contract Placement

Move the most obviously misplaced shared contracts first.

1. Panel IDs

Move:

editor/app/Composition/EditorPanelIds.h

to:

editor/app/Core/Panels/EditorPanelIds.h

Then update all includes to use Core/Panels/EditorPanelIds.h.

Reason: panel IDs are global app model constants, not composition-private implementation details.

2. Workspace Panel Runtime Contract

Split the existing workspace panel registry header:

Current:

editor/app/Features/EditorWorkspacePanelRegistry.h

Target:

editor/app/Core/WorkspacePanels/EditorWorkspacePanelRuntime.h
editor/app/Features/EditorWorkspacePanelRegistry.h

The new core header owns:

• EditorWorkspacePanelCursorKind
• EditorWorkspacePanelUpdatePhase
• EditorWorkspacePanelFrameEvent
• EditorWorkspacePanelInitializationContext
• EditorWorkspacePanelShutdownContext
• EditorWorkspacePanelUpdateContext
• EditorWorkspacePanel
• EditorWorkspacePanelRuntimeSet

The feature registry header owns only:

• CreateEditorWorkspacePanelRuntimeSet()

Reason: composition should depend on the panel runtime interface, not on the feature registry. Concrete feature construction belongs to Features.

3. Keep the First Cut Buildable

This phase should not change behavior.

Expected behavioral diff: none.

Expected dependency improvement:

Composition -> Core/WorkspacePanels
Features    -> Core/WorkspacePanels
Features    -> Core/Panels

This does not fully solve all cycles, but it removes the worst misplaced public contract and creates the landing zone for the next cut.

Completed follow-up:

• EditorPanelServices now carries the panel-facing references to session, project runtime, scene runtime, command focus, color-picker state, system interaction, text measurement, and utility-window requests.
• EditorWorkspacePanelRuntimeSet updates a single phase at a time; Composition owns the command-focus sync point between main panels and after-focus panels.
• Concrete workspace and utility panels use EditorPanelServices and no longer include Composition/EditorContext.h.

Phase 2: Introduce XCEditorCore

Create:

add_library(XCEditorCore STATIC ...)

Initial contents:

• app/Core/**
• app/Commands/**
• app/Composition/**
• app/Features/**
• app/Project/** or app/Services/Project/**
• app/Scene/** or app/Services/Scene/**
• app/State/**
• app/Core/UtilityWindows/**
• app/Core/Windowing/**
• app/Windowing/** core files that do not require Win32 or D3D12
• host-facing abstract interfaces

Keep in XCEditor executable:

• app/main.cpp
• app/Bootstrap/Application.*
• app/Bootstrap/EditorApp.rc
• app/Host/Win32/**
• app/Host/D3D12/**
• any concrete host glue that includes windows.h

XCEditor links XCEditorCore, XCUIEditor, and concrete platform/rendering libraries.

Important: do not hide Win32/D3D12 in XCEditorCore just to make the first CMake edit easier. If a source file needs windows.h, it belongs in the host side until a neutral interface exists.

Phase 3: Restore App-Core And App Feature Tests

Status: completed for the initial app-core and app feature/viewport suites.

Created:

editor_app_core_tests
editor_app_feature_tests

This target links:

XCEditorCore
GTest::gtest_main

The initial suite contains tests that should not need Win32/D3D12:

• test_editor_host_command_bridge.cpp
• test_editor_project_runtime.cpp
• test_editor_shell_asset_validation.cpp
• test_project_browser_model.cpp
• test_hierarchy_scene_binding.cpp
• test_inspector_presentation.cpp

The restored app feature/viewport suite contains:

• test_editor_window_input_routing.cpp
• test_project_panel.cpp
• test_scene_viewport_render_plan.cpp
• test_scene_viewport_runtime.cpp
• test_viewport_object_id_picker.cpp

Completed stale-reference cleanup:

• Ports/SystemInteractionPort.h test use was replaced with SystemInteractionService.h.
• Rendering/Viewport/ViewportRenderTargetInternal.h test use was replaced with current ViewportRenderTargets and ViewportRenderTargetUtils headers.
• app/Platform/Win32/WindowManager/TabDragDropTarget.h was not restored. The test now covers ResolveUIEditorDockHostTabDropTarget from the reusable XCEditor/Docking/UIEditorDockHostTransfer.h API through editor_windowing_phase1_tests.

These test targets are part of the architecture. If app core and app feature/viewport behavior cannot be tested without starting the executable host, the boundary is not real.

Phase 4: Service and Feature Boundary Cleanup

After XCEditorCore exists, remove remaining service-to-feature dependencies.

Project

Completed:

Services/Project/EditorProjectRuntime.h -> Services/Project/ProjectBrowserModel.h
Features/Project/ProjectPanel.h -> Services/Project/EditorProjectRuntime.h

Current shape:

Services/Project/ProjectBrowserModel.h
Services/Project/EditorProjectRuntime.h
Features/Project/ProjectPanel.h

ProjectBrowserModel is now service-owned domain/project state. It exposes folder, asset, and breadcrumb data, while ProjectPanel converts folders into UIEditorTreeViewItem presentation data. Keep future project filesystem and command-target behavior in Services/Project, not under Features/Project.

Scene

Keep scene runtime as a service layer. Scene viewport feature code may use scene services, but scene services should not depend on concrete feature UI.

Utility Windows

Completed:

UtilityWindows/EditorUtilityWindowKind.h
UtilityWindows/EditorUtilityWindowPanel.h
UtilityWindows/EditorUtilityWindowRegistry.*
    -> Core/UtilityWindows/EditorUtilityWindowRuntime.h
    -> Core/UtilityWindows/EditorUtilityWindowRegistry.*
    -> Features/EditorUtilityWindowRegistry.*

Current shape:

Core/UtilityWindows/EditorUtilityWindowRuntime.h
Core/UtilityWindows/EditorUtilityWindowRegistry.*
Features/EditorUtilityWindowRegistry.*

Keep utility kinds, descriptors, host context, panel contract, and factory type in Core/UtilityWindows. Keep concrete utility panel construction in Features/EditorUtilityWindowRegistry.* and inject it from the application composition root. Windowing may resolve descriptors from Core, but must not include Color Picker, Add Component, or other concrete feature-panel headers.

Phase 5: Host Boundary Cleanup

Split neutral host contracts from concrete implementations.

Target:

app/Host/Interfaces/
  EditorWindowHostInterfaces.h
  EditorWindowRenderRuntime.h
  UiTextureHost.h
  ViewportRenderHost.h
  SystemInteractionService.h

app/Host/Win32/
  Win32SystemInteractionHost.*
  EditorWindow.*
  message dispatch, DPI, chrome, pointer capture

app/Host/D3D12/
  D3D12EditorWindowRenderRuntime.*
  D3D12 UI renderer, texture host, text system, swap chain presenter

Then replace concrete Win32/D3D12 cross-includes with a neutral surface or factory contract.

Completed cuts:

• The old Win32EditorWindowRenderRuntimeSurface concrete adapter was removed.
• EditorWindowRenderRuntimeSurface is now a value contract in Host/Interfaces/EditorWindowRenderRuntime.h.
• Win32 fills that neutral contract during native surface capture; D3D12 reads the native handle from the contract instead of including a Win32 editor windowing header.
• Neutral host-facing contracts now live under app/Host/Interfaces/.
• EditorWindowTransferRequests, window screen geometry, and title-bar chrome metrics now live under app/Core/Windowing/.
• XCEditorCore now exposes only app/Core, app/Commands, app/State, and app/Host/Interfaces through its public usage requirements, and both XCEditorCore and XCEditor enumerate explicit module roots instead of using editor/app as a compatibility include directory.
• Concrete Win32 and D3D12 host implementations now live under app/Host/Win32 and app/Host/D3D12; XCEditor consumes those roots privately, while XCEditorCore only sees app/Host/Interfaces.

Phase 6: Documentation Update

Update editor/AGENTS.md after each completed boundary cut.

Required changes:

• production target shape becomes XCUIEditor, XCEditorCore, XCEditor
• Core owns shared app contracts
• Features/EditorWorkspacePanelRegistry.* owns concrete feature factories
• app tests link XCEditorCore
• no new app code should add direct Composition <-> Features cycles

Validation

Run these after each phase where possible:

cmake --build build --config Debug --target XCUIEditor
cmake --build build --config Debug --target XCEditorCore
cmake --build build --config Debug --target XCEditor
cmake --build build --config Debug --target editor_ui_tests
cmake --build build --config Debug --target editor_app_core_tests
cmake --build build --config Debug --target editor_app_feature_tests
cmake --build build --config Debug --target editor_windowing_phase1_tests

When app smoke is available:

ctest -C Debug -R xceditor_smoke --output-on-failure

If XCEditorCore does not exist yet, skip that target until Phase 2 lands.

Done Criteria

The refactor is complete when:

• XCEditorCore.lib exists and is linked by XCEditor.
• XCEditor executable source is limited to host startup and concrete platform/render backend wiring.
• Composition no longer includes concrete feature panel headers.
• Services no longer include Features/**.
• Win32 and D3D12 communicate through neutral host/render contracts.
• app-core and app feature/viewport tests are wired into CMake and build without running the executable.
• editor/AGENTS.md describes the new target shape and directory rules.