XCEngine/docs/plan/editor-engine-services-refactor-plan.md

# EditorEngineServices Refactor Plan

## Problem

The root problem is no longer that `EngineEditorServices.cpp` used to be too large.

That implementation has already been split. The real architectural problem is
still `EditorEngineServices` itself:

- it is a god interface
- it mixes scene backend creation, viewport bridge logic, shader loading,
  object-id resolving, and engine lifecycle
- editor subsystems still depend on one shared service-locator style entrypoint
- new bridge needs will keep accumulating in `editor/app/Services/Engine`
  unless that dependency surface is actively reduced

This refactor must therefore optimize for dependency reduction, not file
splitting.

## Target State

The goal is not "no bridge code".

The goal is "distributed, narrow bridges at clear boundaries instead of one
central editor-to-engine gateway".

The target editor-side interfaces are:

- `EditorSceneBackendFactory`
  - only `CreateSceneBackend`
- `SceneViewportEngineBridge`
  - only scene viewport frame-plan build, render, and object-id resolve
- `GameViewportEngineBridge`
  - only game viewport frame-plan build and render
- `EditorShaderProvider`
  - only shader or resource acquisition
- `EditorEngineLifecycle`
  - only `UpdateAsyncLoads` and `Shutdown`

If `EngineEditorServices.cpp` still exists at the end, it may only exist as an
internal composition-shell implementation. It must not remain a shared runtime
dependency across editor features.

## Freeze Rule

`EditorEngineServices` is now a compatibility shell under freeze:

- no new public methods
- no new feature bridges added to it
- no new panels, tools, passes, or runtimes depending on it
- only subtraction is allowed: move capabilities out of it

Without this rule, the refactor will fail even if some files get cleaner.

## Current Consumer Map

Refactoring must follow actual consumers, not folder aesthetics.

### `EditorContext`

Current usage:

- `CreateSceneBackend`

Conclusion:

- it does not need viewport, shader, game, or lifecycle capabilities
- it should depend only on `EditorSceneBackendFactory`

File:

- `editor/app/Composition/EditorContext.cpp`

### `SceneViewportRenderService`

Current usage:

- `BuildSceneViewportFramePlan`
- `RenderSceneViewportFramePlan`
- `TryResolveActiveSceneRenderObjectId`

Conclusion:

- it should depend only on `SceneViewportEngineBridge`

File:

- `editor/app/Rendering/Viewport/SceneViewportRenderService.cpp`

### `GameViewportRenderService`

Current usage:

- `BuildGameViewportFramePlans`
- `RenderGameViewportFramePlans`

Conclusion:

- it should depend only on `GameViewportEngineBridge`

File:

- `editor/app/Rendering/Viewport/GameViewportRenderService.cpp`

### Scene Viewport Passes

Current usage:

- `LoadShader`

Affected code:

- `SceneViewportGridPass`
- `SceneViewportSelectionOutlinePass`

Conclusion:

- low-level render passes are taking a full engine facade just to load shaders
- this is the wrong dependency direction
- they should depend only on `EditorShaderProvider`

Files:

- `editor/app/Rendering/Viewport/Passes/SceneViewportGridPass.cpp`
- `editor/app/Rendering/Viewport/Passes/SceneViewportSelectionOutlinePass.cpp`

### `Application`

Current usage:

- `UpdateAsyncLoads`
- `Shutdown`

Conclusion:

- it should depend only on `EditorEngineLifecycle`

File:

- `editor/app/Bootstrap/Application.cpp`

## Execution Order

This work should proceed in dependency order, not in arbitrary file order.

### Phase A. Freeze the Interface

Goals:

- document `EditorEngineServices` as a temporary compatibility shell
- enforce the "no new methods" rule in code review and follow-up work

Acceptance:

- `EditorEngineServices.h` clearly states the compatibility-shell role
- no new consumers are introduced

### Phase B. Split by Consumer

Goals:

- remove the easy, high-signal consumers from the god interface first

Execution order:

1. `EditorContext` -> `EditorSceneBackendFactory`
2. `SceneViewportRenderService` -> `SceneViewportEngineBridge`
3. `GameViewportRenderService` -> `GameViewportEngineBridge`
4. `Application` -> `EditorEngineLifecycle`

Why this order:

- low behavior risk
- mostly editor-side injection cleanup
- removes the largest legitimate consumers first

Acceptance:

- those four consumers no longer include or store `EditorEngineServices`
- each one is injected with a narrow dependency

### Phase C. Remove Low-Level Resource Leakage

Goals:

- remove `LoadShader` reach from low-level viewport passes

Execution order:

1. introduce `EditorShaderProvider`
2. migrate `SceneViewportGridPass`
3. migrate `SceneViewportSelectionOutlinePass`

Acceptance:

- scene viewport passes no longer include `EditorEngineServices.h`
- shader access flows through a narrow provider

### Phase D. Collapse the Compatibility Shell

Goals:

- remove the public architectural role of `EditorEngineServices`

Allowed end states:

1. delete `EditorEngineServices`
2. keep only an internal composition object that does not appear in feature,
   runtime, or pass dependencies

Disallowed fake end states:

- split implementation files but keep the same shared public facade forever
- rename the god interface without shrinking its surface

## Non-Goals

This plan intentionally does not include:

- mixing this work with `EditorSceneComponentMutation` typed-command refactors
- copying Unreal Engine module structure mechanically
- removing all bridge code as a principle
- large behavior rewrites when dependency shrinkage is sufficient

## Code Movement Rules

All follow-up implementation should obey these rules:

- interfaces are named by consumer boundary, not by generic service language
- each interface exposes only the methods that one consumer actually uses
- render passes must not depend on scene backend factory or lifecycle code
- composition owns assembly; features and passes must not locate services on
  their own
- bridge code is acceptable only when it stays narrow, local, and scoped to a
  concrete boundary

## Completion Criteria

This refactor is complete only when all of the following are true:

- `EditorContext` no longer depends on `EditorEngineServices`
- `SceneViewportRenderService` no longer depends on `EditorEngineServices`
- `GameViewportRenderService` no longer depends on `EditorEngineServices`
- `Application` no longer depends on `EditorEngineServices`
- scene viewport passes no longer depend on `EditorEngineServices`
- `EditorEngineServices` has gained no new methods
- `editor/app/Services/Engine` has stopped being the default dumping ground for
  every editor-engine bridge

## Immediate Next Cut

The next cut is not "split `EngineEditorServices.cpp` again".

The correct next cut is:

1. define `EditorSceneBackendFactory`
2. make `EditorContext` depend only on that interface
3. remove scene backend creation from the `EditorEngineServices` consumer
   surface

Why this is next:

- it is the safest cut
- it has the narrowest dependency
- it starts emptying `EditorEngineServices` from the top of the editor stack
- it creates the migration template for viewport, game, lifecycle, and shader
  provider splits