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: 11/11
• 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
  • schema consistency rules for:
    • allowedValues only on enum
    • documentKind / restrictDocumentKind only on document
    • explicit documentKind required when restrictDocumentKind=true
• 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.