172 lines
5.0 KiB
Markdown
172 lines
5.0 KiB
Markdown
# XCEditor Windowing Runtime Boundary Refactor Plan
|
|
|
|
## Goal
|
|
|
|
Eliminate the last invalid architectural seam inside the editor windowing stack:
|
|
`Product/Core/Windowing/Contracts` and `Product/Core/Windowing/EditorWorkspaceShellRuntime`
|
|
were pretending to be reusable core abstractions, but they actually described concrete
|
|
editor runtime services and a single concrete shell runtime flow.
|
|
|
|
The target state is:
|
|
|
|
- `Product/Core/Windowing` contains only stable value types and transfer models.
|
|
- `Product/Runtime/Shell` owns shell-definition and workspace-shell runtime services.
|
|
- `Product/Runtime/Diagnostics` owns frame-status and workspace trace services.
|
|
- windowing runtime code binds concrete runtime services directly instead of routing
|
|
them through fake cross-layer contracts.
|
|
|
|
## Root Problem
|
|
|
|
The previous structure had three coupled problems:
|
|
|
|
1. `EditorShellDefinitionProvider`, `EditorFrameStatusService`, and
|
|
`EditorFrameValidation` were not true abstraction boundaries.
|
|
They each had one editor-owned runtime implementation.
|
|
2. `EditorWorkspaceShellRuntime` was stored under `Core`, but its API was tied to
|
|
editor runtime services, shell composition, viewport runtime wiring, and per-frame
|
|
status synchronization.
|
|
3. These pseudo-contracts were threaded through constructor signatures and per-frame
|
|
update contexts, so runtime-specific behavior leaked into supposedly reusable core
|
|
types.
|
|
|
|
This made `Core` look reusable while actually encoding editor runtime policy.
|
|
|
|
## Target Architecture
|
|
|
|
```text
|
|
editor/src/Product/
|
|
Core/
|
|
Windowing/
|
|
EditorShellVariant.h
|
|
EditorWindowGeometry.h
|
|
EditorWindowMetrics.h
|
|
EditorWindowTransferRequests.h
|
|
EditorWindowTypes.h
|
|
Runtime/
|
|
Diagnostics/
|
|
EditorFrameStatusController.*
|
|
WorkspaceTraceEntry.h
|
|
Shell/
|
|
EditorShellDefinitionService.*
|
|
EditorShellRuntime.*
|
|
EditorWorkspaceShellRuntime.h
|
|
Windowing/
|
|
Content/
|
|
Frame/
|
|
Runtime/
|
|
Workspace/
|
|
```
|
|
|
|
Rules:
|
|
|
|
- `Core/Windowing` may only host stable primitive data, geometry, metrics, enums, and
|
|
transfer request types.
|
|
- runtime services must live in `Runtime/*`, even when they are used widely.
|
|
- per-frame content contexts may carry frame data, but not service locators or fake
|
|
contracts for globally owned runtime services.
|
|
- windowing runtime objects may depend directly on concrete editor runtime services
|
|
when there is only one valid implementation.
|
|
|
|
## Execution Stages
|
|
|
|
### Stage 1 - Remove Fake Contracts
|
|
|
|
- Delete `Product/Core/Windowing/Contracts/*`.
|
|
- Delete `Product/Core/Windowing/EditorFrameContracts.h`.
|
|
- remove inheritance from runtime services that were only satisfying those fake
|
|
contracts.
|
|
|
|
Exit condition:
|
|
|
|
- no editor runtime service inherits from `Core/Windowing/Contracts`
|
|
|
|
Status:
|
|
|
|
- completed
|
|
|
|
### Stage 2 - Move Runtime Shell Ownership
|
|
|
|
- Move `EditorWorkspaceShellRuntime` out of `Product/Core/Windowing` into
|
|
`Product/Runtime/Shell`.
|
|
- update all include paths to the runtime-owned shell boundary.
|
|
|
|
Exit condition:
|
|
|
|
- workspace shell runtime is owned only by `Runtime/Shell`
|
|
|
|
Status:
|
|
|
|
- completed
|
|
|
|
### Stage 3 - Rewire Windowing Runtime To Concrete Services
|
|
|
|
- bind `EditorShellDefinitionService` and `EditorFrameStatusController` directly in
|
|
`EditorShellRuntime`
|
|
- bind the same concrete services directly in `EditorWindowRuntimeController` and
|
|
`EditorWindowManager`
|
|
- remove `shellDefinitionProvider` and `frameStatusService` from
|
|
`EditorWindowContentFrameContext`
|
|
- stop passing shell-definition and frame-status pseudo-services through per-frame
|
|
window update calls
|
|
|
|
Exit condition:
|
|
|
|
- the frame loop no longer depends on fake contracts or contract-style service passing
|
|
|
|
Status:
|
|
|
|
- completed
|
|
|
|
### Stage 4 - Physical Cleanup And Audit
|
|
|
|
- remove the empty `Core/Windowing/Contracts` directory
|
|
- search for all old type names and include paths
|
|
- rebuild `XCEditor`
|
|
- run the required 12-second smoke test
|
|
|
|
Exit condition:
|
|
|
|
- no code references the removed contract layer
|
|
- `XCEditor` builds
|
|
- smoke test exits cleanly
|
|
|
|
Status:
|
|
|
|
- completed
|
|
|
|
## Validation
|
|
|
|
Validated on 2026-04-30:
|
|
|
|
- `cmake --build build --config Debug --target XCEditor`
|
|
- smoke test:
|
|
`XCUIEDITOR_SMOKE_TEST=1`
|
|
`XCUIEDITOR_SMOKE_TEST_DURATION_SECONDS=12`
|
|
|
|
Observed result:
|
|
|
|
- build succeeded
|
|
- smoke process exited with `EXIT_CODE=0`
|
|
- measured smoke duration was `14.22` seconds
|
|
|
|
## Final State
|
|
|
|
The root architectural issue is closed when all of the following are true:
|
|
|
|
1. `Product/Core/Windowing` contains only stable value-layer windowing types.
|
|
2. no `Contracts` directory exists under `Product/Core/Windowing`.
|
|
3. `EditorWorkspaceShellRuntime` is runtime-owned, not core-owned.
|
|
4. frame status and shell definition services are concrete runtime services, not
|
|
pseudo-interfaces.
|
|
5. windowing frame code no longer forwards fake contract services per frame.
|
|
6. build and smoke validation both pass.
|
|
|
|
Current status:
|
|
|
|
- all six conditions are satisfied
|
|
|
|
## Marker Audit
|
|
|
|
No `.dog` files are present in the workspace as of the final audit on 2026-04-30, so
|
|
there is no remaining marker file to remove for this refactor.
|