refactor editor product architecture

2026-04-30 20:23:23 +08:00
parent 5ceb9443e7
commit 08968b2df2
280 changed files with 7421 additions and 6816 deletions
--- a/docs/plan/editor-feature-colocation-framework-refactor-plan.md
+++ b/docs/plan/editor-feature-colocation-framework-refactor-plan.md
@@ -0,0 +1,181 @@
+# XCEditor Feature Colocation And Framework Boundary Refactor Plan
+
+## Status
+
+Completed on 2026-04-30.
+
+This document is now the final closure record for the product-layer refactor, not a
+pending migration checklist.
+
+## Goal
+
+Eliminate the old editor product split where:
+
+- feature UI lived under `Product/Content`
+- feature registration lived under `Product/Modules`
+- reusable hosted-content contracts lived under `Product/Hosting`
+
+That structure fragmented ownership, hid real runtime boundaries, and kept the
+registry layer fatter than its name suggested.
+
+## Final Architecture
+
+```text
+editor/src/Product/
+  Commands/
+  Core/
+  Effects/
+  Features/
+    Utility/
+      AddComponent/
+        AddComponentPanel.*
+        AddComponentUtilityFeature.*
+      ColorPicker/
+        ColorPickerPanel.*
+        ColorPickerUtilityFeature.*
+    Workspace/
+      Console/
+        ConsolePanel.*
+        ConsoleWorkspaceFeature.*
+      Game/
+        GameViewportController.*
+        GameViewportFeature.*
+        GameWorkspaceFeature.*
+      Hierarchy/
+        HierarchyModel.*
+        HierarchyPanel.*
+        HierarchyWorkspaceFeature.*
+      Inspector/
+        Components/*
+        InspectorPanel.*
+        InspectorPresentationModel.*
+        InspectorSubject.*
+        InspectorWorkspaceFeature.*
+      Project/
+        ProjectPanel.*
+        ProjectWorkspaceFeature.*
+      Scene/
+        SceneEditCommandRoute.*
+        SceneViewportController.*
+        SceneViewportFeature.*
+        SceneViewportSceneOverlay.*
+        SceneViewportSession.*
+        SceneViewportToolOverlay.*
+        SceneViewportTransformGizmo.*
+        SceneViewportTransformGizmoSupport.*
+        SceneWorkspaceFeature.*
+  Framework/
+    UtilityWindow/
+      EditorUtilityWindowContent.h
+    Workspace/
+      EditorWorkspaceHostedContent.h
+      EditorWorkspaceHostedContentSet.h/.cpp
+  Registry/
+    EditorProductRegistry.h/.cpp
+  Rendering/
+  Runtime/
+    Diagnostics/
+    Features/
+      EditorFeatureComposition.h/.cpp
+    Shell/
+    Store/
+    Windowing/
+  Services/
+  State/
+  Support/
+```
+
+## Final Rules
+
+- `Features/*` owns feature identity, feature-local registration metadata, and feature
+  implementation together.
+- `Framework/*` owns only stable host-facing contracts and generic hosted-content
+  containers.
+- `Registry/*` owns only descriptor types, lookup, and validation.
+- `Runtime/Features/*` owns runtime feature composition and content instantiation.
+- no central `EditorWorkspacePanelIds.h` pool exists; workspace feature identity now
+  lives in the owning feature headers.
+- obsolete `Product/Content`, `Product/Modules`, and `Product/Hosting` trees do not
+  exist anymore.
+
+## What Was Closed
+
+### 1. Framework Boundary
+
+- `Product/Hosting` was replaced by `Product/Framework`.
+- hosted-content contracts were split into:
+  - `EditorWorkspaceHostedContent.h`
+  - `EditorWorkspaceHostedContentSet.h/.cpp`
+  - `EditorUtilityWindowContent.h`
+
+### 2. Feature Colocation
+
+- all workspace feature registration files now sit beside their owning feature UI.
+- all utility feature registration files now sit beside their owning utility content.
+- feature IDs were pulled back into feature-owned headers instead of a centralized
+  workspace panel id table.
+
+### 3. Thin Registry
+
+- `EditorProductModuleRegistry` was replaced by `EditorProductRegistry`.
+- public registration API terminology now uses `Feature`, not `Module`.
+- runtime-specific composition was removed from `Registry` and moved into:
+  - `Product/Runtime/Features/EditorFeatureComposition.*`
+
+### 4. Physical Cleanup
+
+- `Product/Content` was removed.
+- `Product/Modules` was removed.
+- `Product/Hosting` was removed.
+- old include paths and old product registration entry points were removed from the
+  build.
+
+## Validation
+
+Validated during the refactor on 2026-04-30 with repeated build and smoke cycles.
+
+Latest validation commands:
+
+- `cmake --build build --config Debug --target XCEditor`
+- smoke test with:
+  - `XCUIEDITOR_SMOKE_TEST=1`
+  - `XCUIEDITOR_SMOKE_TEST_DURATION_SECONDS=12`
+
+Latest observed smoke result:
+
+- `EXIT_CODE=0`
+- `DURATION_SECONDS=14.25`
+
+## Marker Gate
+
+Final marker audit on 2026-04-30 found a single pending marker file:
+
+- `20260430-154622-394.dog`
+
+That file was deleted only after:
+
+1. obsolete product trees were physically removed
+2. registry responsibilities were reduced to descriptor/lookup/validation only
+3. feature identity ownership was moved back into feature-owned headers
+4. the latest build succeeded
+5. the latest 12-second smoke test exited cleanly
+
+Current marker status:
+
+- no `.dog` files remain in the workspace
+
+## Completion Criteria
+
+The refactor is closed because all of the following are true:
+
+1. `Product/Framework` replaced `Product/Hosting`.
+2. `Product/Features` replaced `Product/Content` and absorbed feature-local
+   registration.
+3. `Product/Registry` replaced `EditorProductModuleRegistry`.
+4. feature behavior and feature registration are physically co-located.
+5. feature identity is no longer stored in a global workspace panel id pool.
+6. the registry is thin and feature-agnostic.
+7. runtime feature assembly lives under `Runtime/Features`.
+8. the latest `XCEditor` build passed.
+9. the latest 12-second smoke test passed.
+10. the `.dog` marker gate was processed after items 1-9 were satisfied.