XCEngine/docs/plan/XCUI_Phase_Status_2026-04-05.md

# XCUI Phase Status 2026-04-05

## Scope

Current execution stays inside the XCUI module and `new_editor`.
Old `editor` replacement is explicitly out of scope for this phase.

## Latest Checkpoint

- Phase 1 sandbox batch committed and pushed as `67a28bd` (`Add XCUI new editor sandbox phase 1`).
- Phase 2 common/runtime batch committed and pushed as `ade5be3` (`Add XCUI runtime screen layer and demo textarea`).
- Phase 3 has now produced a stable mixed batch across common/runtime/editor:
  - schema document definition data is now retained on `UIDocumentModel` and round-trips through the UI artifact path
  - engine runtime coverage was tightened again around `UISystem` and concrete document-host rendering
  - `LayoutLab` continues as the editor widget proving ground for tree/list/property-section style controls
  - the demo sandbox and editor bridge APIs were tightened again without touching the old editor replacement scope
- Old `editor` replacement remains deferred; all active execution still stays inside XCUI shared code and `new_editor`.

## Three-Layer Status

### 1. Common Core

- `UI::DrawData`, input event types, focus routing, style/theme resolution are in active use.
- `UIDocumentCompiler` is buildable again after repairing the duplicated schema helper regression introduced by overlapping schema work.
- `UIDocumentModel` / `UIDocumentResource` now retain schema definition metadata explicitly, including memory accounting and `UISchema` accessors.
- `.xcschema` round-trip coverage is now present through compile, loader, artifact write, and artifact read paths.
- Build-system hardening for MSVC/PDB output paths has started in root CMake, `engine/CMakeLists.txt`, `new_editor/CMakeLists.txt`, and `tests/NewEditor/CMakeLists.txt`.
- Shared engine-side XCUI runtime scaffolding is now present under `engine/include/XCEngine/UI/Runtime` and `engine/src/UI/Runtime`.
- Shared engine-side `UIDocumentScreenHost` now compiles `.xcui` / `.xctheme` screen documents into a runtime-facing document host path instead of leaving all document ownership in `new_editor`.
- Core regression coverage now includes `UIContext`, layout, style, runtime screen player/system, and real document-host tests through `core_ui_tests`.

Current gap:

- Minimal schema self-definition support is landed, but schema-driven validation for `.xcui` / `.xctheme` instances is still not implemented.
- Shared widget/runtime instantiation is still thin and mostly editor-side.
- Common widget primitives are still incomplete: multiline text editing, tree/list virtualization, property-grid composition, and native image/source-rect level APIs.

### 2. Runtime/Game Layer

- The main concrete progress here is that the retained-mode demo runtime now supports a real `TextField` input path with UTF-8 text entry and backspace handling.
- The demo runtime has moved past single-line input: multiline `TextArea` behavior is now covered in the sandbox testbed.
- Engine-side runtime ownership is no longer zero: `UIScreenPlayer`, `UIDocumentScreenHost`, and `UISystem` now define a shared runtime contract for loading a screen document, ticking it with input, and collecting `UI::UIDrawData`.
- `UISystem` now supports layered screen composition semantics: stacked screen players, top-interactive input routing, and modal layers that block lower screens.
- Runtime screen emission now also carries concrete button text in the shared document host path instead of silently dropping button labels.

Current gap:

- No production game-loop integration has been wired yet from scene/runtime systems into `UISystem`.
- The runtime widget library is still shallow and missing the editor-grade controls that will later be shared downward.

### 3. Editor Layer

- `new_editor` remains the isolated XCUI sandbox.
- Native hosted preview is working as `RHI offscreen surface -> ImGui shell texture embed`.
- `XCUI Demo` remains the long-lived effect and behavior testbed.
- `XCUI Demo` now covers both single-line and multiline text authoring behavior, including click caret placement, delete/backspace, tab indentation, and optional text-area line numbers.
- `LayoutLab` now includes a `ScrollView` prototype and a more editor-like three-column authored layout.
- `LayoutLab` now also covers editor-facing widget prototypes: `TreeView`, `TreeItem`, `ListView`, `ListItem`, `PropertySection`, and `FieldRow`.
- Panel diagnostics were expanded to clearly separate preview/runtime/input state and native vs legacy paths.
- The editor bridge layer now has smoke coverage for swapchain after-UI rendering hooks and SRV-backed ImGui texture descriptor registration.
- `XCNewEditor` builds successfully to `build/new_editor/bin/Debug/XCNewEditor.exe`.

Current gap:

- The shell is still ImGui-hosted.
- Editor-specialized widgets are still incomplete at the shared-module level: the authored prototypes exist, but virtualization, selection models, command routing, property editing models, toolbar/menu chrome, and icon-atlas widgets are not yet extracted into reusable XCUI modules.

## Validated This Phase

- `new_editor_xcui_demo_runtime_tests`: `7/7`
- `new_editor_xcui_layout_lab_runtime_tests`: `6/6`
- `new_editor_xcui_rhi_command_compiler_tests`: `6/6`
- `new_editor_xcui_rhi_render_backend_tests`: `5/5`
- `XCNewEditor` Debug target builds successfully
- `core_ui_tests`: `14/14`
- `core_ui_style_tests`: `5/5`
- `ui_resource_tests`: `7/7`
- `editor_tests` targeted bridge smoke: `3/3`

## Landed This Phase

- Demo runtime `TextField` with UTF-8 text insertion, caret state, and backspace.
- Demo runtime multiline `TextArea` path in the sandbox and test coverage for caret movement / multiline input.
- Demo runtime text editing was extended with:
  - click-to-place caret
  - `Delete` support
  - `Tab` / `Shift+Tab` indentation for text areas
  - optional text-area line-number gutter rendering
- Demo authored resources updated to exercise the input field.
- LayoutLab `ScrollView` prototype with clipping and hover rejection outside clipped content.
- LayoutLab editor-widget prototypes for tree/list/property-style sections with dedicated runtime coverage.
- Schema document support extended with:
  - retained `UISchemaDefinition` data on `UIDocumentModel`
  - artifact schema version bump for UI documents
  - loader/resource accessors and memory accounting
  - schema compile/load/artifact regression coverage
- Engine runtime layer added:
  - `UIScreenPlayer`
  - `UIDocumentScreenHost`
  - `UISystem`
  - layered screen composition and modal blocking semantics
- Runtime document-host draw emission now preserves button labels for shared screen rendering.
- RHI image path improvements:
  - clipped image UV adjustment
  - mirrored image UV preservation
  - external texture binding reuse
  - per-batch scissor application
- Editor bridge helpers now expose:
  - an `afterUiRender` swapchain callback hook in `D3D12WindowRenderer`
  - SRV-view based texture descriptor registration in `ImGuiBackendBridge`
  - smoke tests for window renderer, ImGui backend bridge, and console sink registration
- `new_editor` panel/shell diagnostics improvements for hosted preview state.
- XCUI asset document loading changed to prefer direct source compilation before `ResourceManager` fallback for the sandbox path, fixing the LayoutLab crash.
- `UIDocumentCompiler.cpp` repaired enough to restore full local builds after the duplicated schema-helper regression.
- MSVC debug build hardening was tightened again so large parallel `engine` rebuilds stop tripping over compile-PDB contention.

## Phase Risks Still Open

- Schema instance validation is still open beyond `.xcschema` self-definition and artifact round-trip coverage.
- `ScrollView` is still authored/static; no wheel-driven scrolling or virtualization yet.
- `Image` widgets still do not have source-rect/atlas-subregion level API in the high-level draw command model.
- Editor shell still depends on ImGui as host chrome.
- Editor widget coverage is still prototype-driven inside `LayoutLab`; it has not yet been promoted into a reusable shared widget/runtime layer.

## Next Phase

1. Expand schema rules just one level further inside `UIDocumentCompiler.cpp`:
   - `allowedValues` only for `Enum`
   - `documentKind` / `restrictDocumentKind` only for `Document`
   - `restrictDocumentKind=true` requires explicit `documentKind`
2. Expand runtime/game-layer ownership from the current document host + layered `UISystem` into reusable menu/HUD stack patterns and engine runtime integration.
3. Promote the current editor-facing widget prototypes out of authored `LayoutLab` content and into reusable XCUI widget/runtime modules, then continue with toolbar/menu and more native shell-owned chrome.
4. Start the window-level compositor split in `new_editor` so the editor shell can run through `ImGuiHostCompositor` first and then grow a native XCUI compositor path on the same seam.
5. Continue phased validation, commit, push, and plan refresh after each stable batch.