XCEngine/docs/plan/editor-feature-colocation-framework-refactor-plan.md

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

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.