diff --git a/editor/AGENTS.md b/editor/AGENTS.md index 23f4c1ab..7a9d5f7f 100644 --- a/editor/AGENTS.md +++ b/editor/AGENTS.md @@ -12,19 +12,23 @@ real directory tree, trust the code and update this file in the same change. The important production targets are: - `XCUIEditorLib`: reusable XCEditor framework code from `editor/src` and - `editor/include/XCEditor`. + `editor/include/XCEditor`, including the reusable window authority, + synchronization planner, and presentation projection under + `XCEditor/Windowing`. - `XCUIEditorAppWindowing`: app-internal static library for the current - window authority, planner, store, presentation policy, host contracts, - content controllers, coordinators, frame transfer flow, and window manager. + host contracts, content controllers, coordinators, frame transfer flow, and + window manager. - `XCUIEditorApp`: concrete editor executable. Its output name is `XCEngine`. Do not invent target boundaries that are not present in `editor/CMakeLists.txt`. Names such as `XCUIEditorAppCore`, `XCUIEditorAppLib`, and `XCUIEditorHost` are not current production library boundaries in this checkout. -There is no public `editor/include/XCEditor/Windowing` layer yet. Windowing is -currently an app-internal architecture under `editor/app/Windowing` plus the -concrete Win32 host under `editor/app/Platform/Win32`. +There is now a narrow public `editor/include/XCEditor/Windowing` layer for the +generic window authority model, synchronization plan/planner, and presentation +projection. App-specific window orchestration remains under +`editor/app/Windowing`, and the concrete Win32 host remains under +`editor/app/Platform/Win32`. ## Layering @@ -33,12 +37,12 @@ Use these ownership boundaries when changing code: - `editor/include/XCEditor` and `editor/src`: reusable editor framework. Keep this layer independent from app state, Win32, D3D12 host code, and `App::*` types. +- `editor/include/XCEditor/Windowing` and `editor/src/Windowing`: reusable + window authority, validation, synchronization planning, commit, and + presentation projection. Keep this layer generic and free of app content, + host runtime, native platform, and rendering details. - `editor/app/Composition`, `Commands`, `Features`, `Project`, `Scene`, `State`, `System`, `UtilityWindows`: editor product semantics. -- `editor/app/Windowing/System`: authoritative window set, validation, - synchronization planning, and commit. -- `editor/app/Windowing/Presentation`: projection policy derived from - authoritative state. - `editor/app/Windowing/Content`, `Coordinator`, `Frame`, `Host`: platform neutral app window orchestration. - `editor/app/Platform/Win32`: native window, message dispatch, input, @@ -50,7 +54,7 @@ The semantic dependency direction should remain: ```text XCEditor framework <- editor app semantics - <- app windowing + <- app windowing runtime <- Win32 host / rendering host ``` @@ -156,7 +160,11 @@ logic. - First decide whether the change belongs to XCEditor framework, app semantics, app windowing, Win32 host, or rendering host. - Keep public framework headers free of `App::*`, Win32, and D3D12 host types. -- Use `editor/app/Windowing` for window semantics that are not inherently Win32. +- Use `editor/include/XCEditor/Windowing` and `editor/src/Windowing` for + generic window authority, synchronization, validation, and presentation + projection. +- Use `editor/app/Windowing` for app-specific window runtime semantics, + content, frame transfer, host contracts, and coordinators. - Use `editor/app/Platform/Win32` only for native host behavior and message integration. - Do not let `editor/app/Windowing` include `Platform/Win32` or D3D12 concrete @@ -168,25 +176,21 @@ logic. - Use synchronization plans for operations that create, close, replace, or reconcile workspace windows. - Use frame transfer requests only for host-side or cross-window effects. -- Do not describe `XCEditor/Windowing` as an existing framework/public layer. ## Current Architecture Debt -The highest-value windowing boundary has been hardened: `XCUIEditorAppWindowing` -now owns the app-internal window authority, presentation, content controller -factory, coordinators, frame transfer flow, host contracts, and manager. The -Win32 host is the concrete native adapter and creates native host windows from -content supplied by app windowing. +The highest-value windowing boundary has been hardened: `XCUIEditorLib` now +owns the reusable window authority, synchronization planner, workspace store, +and presentation projection under `XCEditor/Windowing`. `XCUIEditorAppWindowing` +owns the app-internal content controller factory, coordinators, frame transfer +flow, host contracts, and manager. The Win32 host is the concrete native +adapter and creates native host windows from content supplied by app windowing. -The main remaining debt is promotion discipline. `XCUIEditorAppWindowing` is -still app-internal and may depend on app semantics such as `EditorContext`, -`EditorShellRuntime`, utility window descriptors, and product-specific content. -Do not promote this surface to `XCEditor` until the authority model, host -interfaces, frame transfer contract, and presentation projection are stable and -generic enough to expose. - -Do not paper over this debt by documenting a public windowing framework that -does not exist. +The main remaining debt is promotion discipline around the app runtime surface. +`XCUIEditorAppWindowing` is still app-internal and may depend on app semantics +such as `EditorContext`, `EditorShellRuntime`, utility window descriptors, and +product-specific content. Do not promote host interfaces, frame transfer, or +content controllers to `XCEditor` until they are generic enough to expose. ## Validation @@ -223,10 +227,15 @@ Start with these files for editor/windowing work: - `editor/app/Composition/EditorShellRuntime.*` - `editor/include/XCEditor/Workspace/UIEditorWorkspaceController.h` - `editor/src/Workspace/UIEditorWorkspaceController.cpp` -- `editor/app/Windowing/System/EditorWindowSystem.*` -- `editor/app/Windowing/System/EditorWindowWorkspaceStore.*` -- `editor/app/Windowing/System/EditorWindowSynchronizationPlanner.*` -- `editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.*` +- `editor/include/XCEditor/Windowing/System/EditorWindowSystem.h` +- `editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlan.h` +- `editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlanner.h` +- `editor/include/XCEditor/Windowing/Presentation/EditorWorkspaceWindowProjection.h` +- `editor/include/XCEditor/Windowing/Presentation/EditorWindowPresentationPolicy.h` +- `editor/src/Windowing/System/EditorWindowSystem.cpp` +- `editor/src/Windowing/System/EditorWindowWorkspaceStore.*` +- `editor/src/Windowing/System/EditorWindowSynchronizationPlanner.cpp` +- `editor/src/Windowing/Presentation/EditorWindowPresentationPolicy.cpp` - `editor/app/Windowing/Host/EditorWindowHostInterfaces.h` - `editor/app/Windowing/Content/EditorWindowContentController.h` - `editor/app/Windowing/Content/EditorWindowContentFactory.*` @@ -242,3 +251,35 @@ Start with these files for editor/windowing work: - `tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp` - `tests/UI/Editor/unit/CMakeLists.txt` - `tests/UI/Editor/smoke/CMakeLists.txt` + +## 上一刀 + +上一刀把窗口权威核心从 app-internal 层真正切到 framework 层。具体来说： +`EditorWindowSystem`、`EditorWindowSynchronizationPlan`、 +`EditorWindowSynchronizationPlanner`、`EditorWorkspaceWindowProjection` 和 +`EditorWindowPresentationPolicy` 的公共头移到 +`editor/include/XCEditor/Windowing`；对应实现移到 `editor/src/Windowing`。 +`EditorWindowWorkspaceStore` 只作为 framework 私有实现保留在 +`editor/src/Windowing/System`，没有暴露到 public include 面。 + +构建边界也同步收紧：这些 window authority / synchronization / presentation +sources 现在编进 `XCUIEditorLib`，不再属于 `XCUIEditorAppWindowing`； +`XCUIEditorAppWindowing` 的 `editor/app` include 从 `PUBLIC` 改成 `PRIVATE`。 +这意味着下游不能再因为链接 app windowing 目标而顺手拿到整个 app include 面。 + +app 层只改成依赖新的 framework include，例如 +`` 和 +``。 +`editor/app/Windowing` 仍然保留 app-specific 的 content controllers、 +coordinators、frame transfer、host contracts 和 `EditorWindowManager`； +`editor/app/Platform/Win32` 仍然只做 native host/window/message/runtime 适配。 + +测试边界也跟着改了：`editor_windowing_phase1_tests` 现在只链接 +`XCUIEditorLib`，不再链接 `XCUIEditorAppWindowing`，也不再把 `editor/app` +和 `editor/src` 作为测试 include 目录。这个测试因此只验证公开的 +`XCEditor/Windowing` 权威模型，而不是穿透 app 内部目录。 + +这一刀没有把整个 `app/Windowing` 提升到 `XCEditor`。故意没有提升的部分包括 +`EditorContext`、`EditorShellRuntime`、utility window descriptor/panel、 +frame transfer request、host interface、content controller、coordinator 和 Win32 host。 +这些仍然是产品运行时/宿主编排职责，不是 framework windowing kernel。 diff --git a/editor/CMakeLists.txt b/editor/CMakeLists.txt index 0c39ee80..f5d0d412 100644 --- a/editor/CMakeLists.txt +++ b/editor/CMakeLists.txt @@ -130,6 +130,13 @@ set(XCUI_EDITOR_WORKSPACE_SOURCES src/Workspace/UIEditorWindowWorkspaceModel.cpp ) +set(XCUI_EDITOR_WINDOWING_SOURCES + src/Windowing/Presentation/EditorWindowPresentationPolicy.cpp + src/Windowing/System/EditorWindowSynchronizationPlanner.cpp + src/Windowing/System/EditorWindowSystem.cpp + src/Windowing/System/EditorWindowWorkspaceStore.cpp +) + set(XCUI_EDITOR_WIDGET_SUPPORT_SOURCES src/Widgets/UIEditorCollectionPrimitives.cpp src/Widgets/UIEditorColorUtils.cpp @@ -146,6 +153,7 @@ set(XCUI_EDITOR_SHARED_SOURCES ${XCUI_EDITOR_SHELL_SOURCES} ${XCUI_EDITOR_VIEWPORT_SOURCES} ${XCUI_EDITOR_WORKSPACE_SOURCES} + ${XCUI_EDITOR_WINDOWING_SOURCES} ${XCUI_EDITOR_WIDGET_SUPPORT_SOURCES} ) @@ -179,17 +187,13 @@ set(XCUI_EDITOR_APP_WINDOWING_SOURCES app/Windowing/Content/EditorUtilityWindowContentController.cpp app/Windowing/Content/EditorWorkspaceWindowContentController.cpp app/Windowing/Frame/EditorWindowFrameOrchestrator.cpp - app/Windowing/Presentation/EditorWindowPresentationPolicy.cpp - app/Windowing/System/EditorWindowSynchronizationPlanner.cpp - app/Windowing/System/EditorWindowSystem.cpp - app/Windowing/System/EditorWindowWorkspaceStore.cpp ) add_library(XCUIEditorAppWindowing STATIC ${XCUI_EDITOR_APP_WINDOWING_SOURCES} ) -target_include_directories(XCUIEditorAppWindowing PUBLIC +target_include_directories(XCUIEditorAppWindowing PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/app ) diff --git a/editor/app/Bootstrap/Application.cpp b/editor/app/Bootstrap/Application.cpp index fdac0a83..f4888658 100644 --- a/editor/app/Bootstrap/Application.cpp +++ b/editor/app/Bootstrap/Application.cpp @@ -12,7 +12,7 @@ #include "Support/ExecutablePath.h" #include -#include "Windowing/System/EditorWindowSystem.h" +#include #include #include diff --git a/editor/app/Windowing/Content/EditorWindowContentController.h b/editor/app/Windowing/Content/EditorWindowContentController.h index b4e358fd..4882e4d1 100644 --- a/editor/app/Windowing/Content/EditorWindowContentController.h +++ b/editor/app/Windowing/Content/EditorWindowContentController.h @@ -4,7 +4,7 @@ #include #include -#include "Windowing/Presentation/EditorWorkspaceWindowProjection.h" +#include #include #include diff --git a/editor/app/Windowing/Content/EditorWindowContentFactory.cpp b/editor/app/Windowing/Content/EditorWindowContentFactory.cpp index 5dad43fa..c05f2f97 100644 --- a/editor/app/Windowing/Content/EditorWindowContentFactory.cpp +++ b/editor/app/Windowing/Content/EditorWindowContentFactory.cpp @@ -3,7 +3,7 @@ #include "Windowing/Content/EditorUtilityWindowContentController.h" #include "Windowing/Content/EditorWorkspaceWindowContentController.h" -#include "Windowing/System/EditorWindowSystem.h" +#include #include diff --git a/editor/app/Windowing/Content/EditorWorkspaceWindowContentController.cpp b/editor/app/Windowing/Content/EditorWorkspaceWindowContentController.cpp index 0e882663..723f968b 100644 --- a/editor/app/Windowing/Content/EditorWorkspaceWindowContentController.cpp +++ b/editor/app/Windowing/Content/EditorWorkspaceWindowContentController.cpp @@ -1,8 +1,8 @@ #include "Windowing/Content/EditorWorkspaceWindowContentController.h" #include -#include "Windowing/Presentation/EditorWindowPresentationPolicy.h" -#include "Windowing/System/EditorWindowSystem.h" +#include +#include #include namespace XCEngine::UI::Editor::App { diff --git a/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.cpp b/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.cpp index ac818eab..b08e92b1 100644 --- a/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.cpp +++ b/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.cpp @@ -5,8 +5,8 @@ #include "Windowing/Coordinator/EditorWindowLifecycleCoordinator.h" #include -#include "Windowing/Presentation/EditorWindowPresentationPolicy.h" -#include "Windowing/System/EditorWindowSystem.h" +#include +#include #include #include #include diff --git a/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.h b/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.h index ae743797..6cad5129 100644 --- a/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.h +++ b/editor/app/Windowing/Coordinator/EditorWindowWorkspaceCoordinator.h @@ -7,8 +7,8 @@ #include "Windowing/Frame/EditorWindowTransferRequests.h" #include "Windowing/Host/EditorWindowHostInterfaces.h" -#include "Windowing/Presentation/EditorWorkspaceWindowProjection.h" -#include "Windowing/System/EditorWindowSynchronizationPlan.h" +#include +#include #include #include diff --git a/editor/app/Windowing/Host/EditorWindowHostInterfaces.h b/editor/app/Windowing/Host/EditorWindowHostInterfaces.h index 1812c1a3..1accf8b9 100644 --- a/editor/app/Windowing/Host/EditorWindowHostInterfaces.h +++ b/editor/app/Windowing/Host/EditorWindowHostInterfaces.h @@ -5,7 +5,7 @@ #include "Windowing/Host/EditorWindowPointerCapture.h" #include "Windowing/Host/EditorWindowTypes.h" -#include "Windowing/Presentation/EditorWorkspaceWindowProjection.h" +#include #include #include diff --git a/editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.h b/editor/include/XCEditor/Windowing/Presentation/EditorWindowPresentationPolicy.h similarity index 89% rename from editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.h rename to editor/include/XCEditor/Windowing/Presentation/EditorWindowPresentationPolicy.h index 1422eb52..43df837c 100644 --- a/editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.h +++ b/editor/include/XCEditor/Windowing/Presentation/EditorWindowPresentationPolicy.h @@ -1,6 +1,6 @@ #pragma once -#include "Windowing/Presentation/EditorWorkspaceWindowProjection.h" +#include #include #include diff --git a/editor/app/Windowing/Presentation/EditorWorkspaceWindowProjection.h b/editor/include/XCEditor/Windowing/Presentation/EditorWorkspaceWindowProjection.h similarity index 100% rename from editor/app/Windowing/Presentation/EditorWorkspaceWindowProjection.h rename to editor/include/XCEditor/Windowing/Presentation/EditorWorkspaceWindowProjection.h diff --git a/editor/app/Windowing/System/EditorWindowSynchronizationPlan.h b/editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlan.h similarity index 100% rename from editor/app/Windowing/System/EditorWindowSynchronizationPlan.h rename to editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlan.h diff --git a/editor/app/Windowing/System/EditorWindowSynchronizationPlanner.h b/editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlanner.h similarity index 78% rename from editor/app/Windowing/System/EditorWindowSynchronizationPlanner.h rename to editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlanner.h index 68e25591..1650b648 100644 --- a/editor/app/Windowing/System/EditorWindowSynchronizationPlanner.h +++ b/editor/include/XCEditor/Windowing/System/EditorWindowSynchronizationPlanner.h @@ -1,6 +1,6 @@ #pragma once -#include "Windowing/System/EditorWindowSynchronizationPlan.h" +#include namespace XCEngine::UI::Editor { diff --git a/editor/app/Windowing/System/EditorWindowSystem.h b/editor/include/XCEditor/Windowing/System/EditorWindowSystem.h similarity index 96% rename from editor/app/Windowing/System/EditorWindowSystem.h rename to editor/include/XCEditor/Windowing/System/EditorWindowSystem.h index 9fa42d03..283a1f65 100644 --- a/editor/app/Windowing/System/EditorWindowSystem.h +++ b/editor/include/XCEditor/Windowing/System/EditorWindowSystem.h @@ -1,12 +1,13 @@ #pragma once -#include "Windowing/System/EditorWindowSynchronizationPlan.h" +#include #include #include #include #include #include +#include namespace XCEngine::UI::Editor { diff --git a/editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.cpp b/editor/src/Windowing/Presentation/EditorWindowPresentationPolicy.cpp similarity index 97% rename from editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.cpp rename to editor/src/Windowing/Presentation/EditorWindowPresentationPolicy.cpp index 7cd059fb..89f3be6c 100644 --- a/editor/app/Windowing/Presentation/EditorWindowPresentationPolicy.cpp +++ b/editor/src/Windowing/Presentation/EditorWindowPresentationPolicy.cpp @@ -1,4 +1,4 @@ -#include "Windowing/Presentation/EditorWindowPresentationPolicy.h" +#include #include #include diff --git a/editor/app/Windowing/System/EditorWindowSynchronizationPlanner.cpp b/editor/src/Windowing/System/EditorWindowSynchronizationPlanner.cpp similarity index 97% rename from editor/app/Windowing/System/EditorWindowSynchronizationPlanner.cpp rename to editor/src/Windowing/System/EditorWindowSynchronizationPlanner.cpp index 8cc77aad..2d51b461 100644 --- a/editor/app/Windowing/System/EditorWindowSynchronizationPlanner.cpp +++ b/editor/src/Windowing/System/EditorWindowSynchronizationPlanner.cpp @@ -1,6 +1,6 @@ -#include "Windowing/System/EditorWindowSynchronizationPlanner.h" +#include -#include "Windowing/Presentation/EditorWindowPresentationPolicy.h" +#include #include #include diff --git a/editor/app/Windowing/System/EditorWindowSystem.cpp b/editor/src/Windowing/System/EditorWindowSystem.cpp similarity index 98% rename from editor/app/Windowing/System/EditorWindowSystem.cpp rename to editor/src/Windowing/System/EditorWindowSystem.cpp index fd47fc47..c2c26b9c 100644 --- a/editor/app/Windowing/System/EditorWindowSystem.cpp +++ b/editor/src/Windowing/System/EditorWindowSystem.cpp @@ -1,6 +1,6 @@ -#include "Windowing/System/EditorWindowSystem.h" +#include -#include "Windowing/System/EditorWindowSynchronizationPlanner.h" +#include #include "Windowing/System/EditorWindowWorkspaceStore.h" #include diff --git a/editor/app/Windowing/System/EditorWindowWorkspaceStore.cpp b/editor/src/Windowing/System/EditorWindowWorkspaceStore.cpp similarity index 100% rename from editor/app/Windowing/System/EditorWindowWorkspaceStore.cpp rename to editor/src/Windowing/System/EditorWindowWorkspaceStore.cpp diff --git a/editor/app/Windowing/System/EditorWindowWorkspaceStore.h b/editor/src/Windowing/System/EditorWindowWorkspaceStore.h similarity index 100% rename from editor/app/Windowing/System/EditorWindowWorkspaceStore.h rename to editor/src/Windowing/System/EditorWindowWorkspaceStore.h diff --git a/tests/UI/Editor/unit/CMakeLists.txt b/tests/UI/Editor/unit/CMakeLists.txt index bdb258b2..43c473fa 100644 --- a/tests/UI/Editor/unit/CMakeLists.txt +++ b/tests/UI/Editor/unit/CMakeLists.txt @@ -104,16 +104,13 @@ add_executable(editor_windowing_phase1_tests target_link_libraries(editor_windowing_phase1_tests PRIVATE - XCUIEditorAppWindowing XCUIEditorLib GTest::gtest_main ) target_include_directories(editor_windowing_phase1_tests PRIVATE - ${CMAKE_SOURCE_DIR}/editor/app ${CMAKE_SOURCE_DIR}/editor/include - ${CMAKE_SOURCE_DIR}/editor/src ${CMAKE_SOURCE_DIR}/engine/include ) diff --git a/tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp b/tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp index 7ed0ba7e..d85dff19 100644 --- a/tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp +++ b/tests/UI/Editor/unit/test_editor_window_synchronization_planner.cpp @@ -1,8 +1,8 @@ #include -#include "Windowing/Presentation/EditorWindowPresentationPolicy.h" -#include "Windowing/System/EditorWindowSynchronizationPlan.h" -#include "Windowing/System/EditorWindowSystem.h" +#include +#include +#include #include #include #include