XCEngine/docs/plan/NewEditor_FrameLifecycleRuntimeRefactorPlan_2026-04-22.md

NewEditor Frame/Lifecycle Runtime Refactor Plan

Date: 2026-04-22

1. Objective

This plan targets the highest-priority remaining architecture debt in new_editor:

1. frame execution still has multiple live owners
2. window destruction still has multiple live owners
3. EditorShellRuntime is still a per-frame god-object

The goal is not to split files mechanically. The goal is to collapse ownership so that:

1. only one module can drive a frame
2. only one module can finalize window death
3. EditorShellRuntime becomes a thin facade over explicit per-frame stages

2. Confirmed Root Issues

2.1 Frame scheduling is not single-owner

RenderFrame() is currently called from:

• main host render loop
• WM_PAINT
• WM_SIZE
• WM_DPICHANGED
• WM_EXITSIZEMOVE
• borderless chrome transition logic

This means rendering is still driven by both:

1. the normal frame loop
2. synchronous Win32 message-side side effects

As long as this remains true, frame timing, transfer request ordering, and present timing will keep depending on which path happened to trigger first.

2.2 Window lifetime is not single-owner

Shutdown(), DestroyWindow(...), MarkDestroyed(), and host erase currently happen from multiple places in WindowManager, host runtime, and workspace coordination.

This means there is still no single authoritative answer to:

1. who requests close
2. who observes native window destruction
3. who shuts runtime down
4. who removes the managed window from the host container

This is the same root class of problem that previously caused sub-window close regressions.

2.3 EditorShellRuntime still owns too many per-frame responsibilities

EditorShellRuntime::Update(...) still performs, in one place:

1. shell definition build
2. workspace/session sync
3. dock host interaction update
4. viewport request/update
5. hosted panel input routing
6. hosted panel update
7. status/trace/command-focus synchronization

That makes the runtime difficult to reason about and causes unrelated per-frame concerns to stay tightly coupled.

3. Target End State

After this refactor:

1. only one frame driver can execute BeginFrame -> UpdateAndAppend -> Present
2. Win32 message dispatch only records frame requests / dirty reasons, never renders directly
3. borderless chrome logic can request a new frame, but cannot render directly
4. only one lifecycle coordinator can finalize managed window destruction
5. WorkspaceCoordinator can request a window-set mutation, but cannot directly destroy windows
6. EditorShellRuntime becomes a thin composition facade over smaller stage modules

4. New Modules

4.1 Frame ownership

Add:

• new_editor/app/Platform/Win32/EditorWindowFrameDriver.h
• new_editor/app/Platform/Win32/EditorWindowFrameDriver.cpp
• new_editor/app/Platform/Win32/EditorWindowFrameRequest.h

Responsibilities:

• own the only live path that executes a frame
• consume frame request reasons / dirty state
• normalize when transfer requests are collected and applied

4.2 Lifecycle ownership

Add:

• new_editor/app/Platform/Win32/WindowManager/EditorWindowLifecycleCoordinator.h
• new_editor/app/Platform/Win32/WindowManager/EditorWindowLifecycleCoordinator.cpp

Responsibilities:

• own close request state
• own runtime shutdown sequencing
• own native destroy finalization and managed erase
• own primary-window cascade behavior

4.3 Shell runtime stage split

Add:

• new_editor/app/Composition/EditorShellSessionCoordinator.h
• new_editor/app/Composition/EditorShellSessionCoordinator.cpp
• new_editor/app/Composition/EditorShellInteractionEngine.h
• new_editor/app/Composition/EditorShellInteractionEngine.cpp
• new_editor/app/Composition/EditorShellHostedPanelCoordinator.h
• new_editor/app/Composition/EditorShellHostedPanelCoordinator.cpp
• new_editor/app/Composition/EditorShellDrawComposer.h
• new_editor/app/Composition/EditorShellDrawComposer.cpp

Responsibilities:

• SessionCoordinator: context/workspace/session/command-focus/status synchronization
• InteractionEngine: shell definition, dock host interaction, shell frame/state update
• HostedPanelCoordinator: hosted panel input filtering, panel update, panel capture ownership
• DrawComposer: shell draw packets, panel draw packets, viewport frame application to draw data

5. Refactor Strategy

Phase A. Collapse frame execution to one driver

Refactor current flow so that:

1. EditorWindowHostRuntime requests frame execution through EditorWindowFrameDriver
2. EditorWindowMessageDispatcher no longer calls RenderFrame(...) directly
3. EditorWindowChromeController no longer calls RenderFrame(...) directly
4. EditorWindow no longer exposes uncontrolled render entrypoints to unrelated callers

Message-side behavior must become:

• mark dirty
• enqueue reason
• invalidate host window when needed

But never:

• begin a frame
• build draw data
• present directly

Phase B. Collapse lifecycle to one owner

Refactor current flow so that:

1. WM_CLOSE only means RequestClose
2. WM_DESTROY only reports native death
3. EditorWindowLifecycleCoordinator becomes the only place that can:
   • call Shutdown()
   • finalize managed destruction
   • erase the managed window from host storage
   • cascade close from the primary window
4. WorkspaceCoordinator stops duplicating host destroy logic

Phase C. Split EditorShellRuntime by stage, not by helper dumping

Do not split by random utility extraction. Split by stage ownership:

1. session sync stage
2. shell interaction stage
3. hosted panel stage
4. draw composition stage

EditorShellRuntime should remain as a thin orchestrating facade that wires these stages together in a stable order.

Phase D. Normalize panel capture ownership

As part of hosted panel coordination:

1. stop hardcoding panel capture checks directly in the runtime facade where possible
2. centralize panel capture ownership through one hosted-panel coordination boundary
3. make it explicit which hosted panels participate in pointer-stream ownership decisions

6. File-Level Impact

6.1 Existing files to shrink / re-scope

• new_editor/app/Platform/Win32/EditorWindow.cpp
• new_editor/app/Platform/Win32/EditorWindow.h
• new_editor/app/Platform/Win32/EditorWindowChromeController.cpp
• new_editor/app/Platform/Win32/WindowManager/EditorWindowHostRuntime.cpp
• new_editor/app/Platform/Win32/WindowManager/EditorWindowHostRuntime.h
• new_editor/app/Platform/Win32/WindowManager/EditorWindowMessageDispatcher.cpp
• new_editor/app/Platform/Win32/WindowManager/EditorWindowWorkspaceCoordinator.cpp
• new_editor/app/Composition/EditorShellRuntime.cpp
• new_editor/app/Composition/EditorShellRuntime.h

6.2 Build graph

Update:

• new_editor/CMakeLists.txt

to register the new frame/lifecycle/runtime stage units.

7. Validation

7.1 Structural validation

After completion:

1. direct RenderFrame(...) call sites outside the frame driver must be gone
2. duplicate Shutdown()/DestroyWindow()/MarkDestroyed()/erase chains must be gone
3. WorkspaceCoordinator must no longer perform raw window destruction
4. EditorShellRuntime facade must delegate to explicit stage modules

7.2 Runtime validation

Must validate:

1. editor starts normally
2. main window continues rendering normally
3. resize / maximize / drag-restore no longer perform direct message-side rendering
4. detached panel windows and tool windows still open/close correctly
5. closing child windows does not close the main window
6. closing the primary window still cascades correctly
7. frame transfer requests still behave correctly during docking / detach workflows

8. Execution Order

1. introduce frame request model and frame driver
2. remove message-side and chrome-side direct rendering
3. introduce lifecycle coordinator
4. remove duplicate destroy/shutdown ownership from host runtime and workspace coordinator
5. split EditorShellRuntime into session/interaction/panel/draw stages
6. rebuild and smoke-test
7. perform structural grep validation

9. Success Criteria

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

1. new_editor frame execution has a single live owner
2. new_editor managed window destruction has a single live owner
3. EditorShellRuntime is no longer a monolithic per-frame god-object
4. resize / dpi / chrome transitions no longer trigger direct rendering from message handlers
5. build and smoke validation both pass