docs: tighten xcui backend doc boundaries

docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md

@@ -6,40 +6,48 @@
 
 **源文件**: `editor/src/XCUIBackend/ImGuiTransitionBackend.h`
 
-**描述**: 把 `UIDrawList` / `UIDrawData` 过渡性地刷到 Dear ImGui `ImDrawList` 的桥接器。
+**描述**: 把 `UIDrawList` / `UIDrawData` 过渡性翻译到 Dear ImGui `ImDrawList` 的桥接器。
 
 ## 概览
 
-`ImGuiTransitionBackend` 解决的是“XCUI 已经有 draw command，但 editor 主窗口仍由 ImGui 承载”这个过渡问题。
-它当前做三件事：
+`ImGuiTransitionBackend` 解决的是“XCUI 已经生成 draw command，但 editor 宿主窗口仍由 ImGui 承载”的过渡问题。按当前头文件实现，它只负责三段式流程：
 
-- 在 `BeginFrame()` 清空上一帧待刷数据
-- 用 `Submit(...)` 收集 `UIDrawList` 或 `UIDrawData`
-- 在 `EndFrame(...)` 把命令翻译成 `ImDrawList` 调用
+- `BeginFrame()` 清空上一帧积累的 pending draw data 统计。
+- `Submit(...)` 复制或移动收集 `UIDrawList` / `UIDrawData`。
+- `EndFrame(...)` 把 pending 命令翻译成 `ImDrawList` 调用并清空队列。
 
-## 当前行为
+## 当前公开接口
 
-- `BeginFrame()` 会同时重置：
-  - `m_pendingDrawLists`
-  - `m_pendingCommandCount`
-  - `m_lastFlushedDrawListCount`
-  - `m_lastFlushedCommandCount`
-- `Submit(const UIDrawData&)` 当前只是遍历内部 draw list 后逐个转发到 `Submit(const UIDrawList&)`。
-- `EndFrame(...)` 默认落到 `ImGui::GetWindowDrawList()`；如果目标 draw list 为空，会清空 pending state 并返回 `false`。
-- flush 时会维护 `clipDepth`；即便调用方忘了显式补足 `PopClipRect`，函数也会在尾部补弹所有未闭合 clip。
-- `Text` 命令在 `fontSize <= 0` 时回退到 `ImGui::GetFontSize()`。
-- `Image` 命令当前要求 `UITextureHandle::IsValid()` 为真，并且固定使用整张纹理，不消费 `UIDrawCommand.uvMin / uvMax`。
+| 接口 | 作用 |
+|------|------|
+| `BeginFrame()` | 重置 pending 队列和上一帧 flush 统计。 |
+| `Submit(const UIDrawList&)` / `Submit(UIDrawList&&)` | 追加单个 draw list。 |
+| `Submit(const UIDrawData&)` | 遍历 `UIDrawData` 内的全部 draw list 并逐个提交。 |
+| `HasPendingDrawData()` | 判断当前是否已有待 flush 的 draw list。 |
+| `GetPendingDrawListCount()` / `GetPendingCommandCount()` | 查询当前 pending 规模。 |
+| `GetLastFlushedDrawListCount()` / `GetLastFlushedCommandCount()` | 查询上一次成功 flush 的统计。 |
+| `EndFrame(ImDrawList* targetDrawList = nullptr)` | 执行命令翻译；未传目标时默认写到 `ImGui::GetWindowDrawList()`。 |
 
-## 当前调用链
+## 当前实现行为
 
-- `tests/Editor/test_xcui_imgui_transition_backend.cpp` 当前直接验证了 pending state 重置和 flush 后 `ImDrawList` 顶点 / 命令缓冲被写入。
-- `editor/src/XCUIBackend/XCUIDemoRuntime.h` 当前声明了一套会产出 `UIDrawData` 的 demo runtime 接口，与这个桥接器共同构成 XCUI 过渡渲染链路里的最小 source-backed 锚点。
+- `BeginFrame()` 会同时清零 `m_lastFlushedDrawListCount`、`m_lastFlushedCommandCount`、`m_pendingCommandCount`，并清空 `m_pendingDrawLists`。
+- `Submit(const UIDrawData&)` 没有额外批处理逻辑，只是遍历 `drawData.GetDrawLists()` 后转发到单列表重载。
+- `EndFrame(...)` 在目标 draw list 为空时会直接 `ClearPendingState()` 并返回 `false`。
+- flush 期间用 `clipDepth` 跟踪 `PushClipRect` / `PopClipRect`；如果命令流没有正确配平，函数尾部会主动补齐剩余 `PopClipRect()`。
+- `Text` 命令在 `fontSize <= 0.0f` 时回退到 `ImGui::GetFontSize()`。
+- `Image` 命令要求 `UITextureHandle::IsValid()` 为真，并固定使用整张纹理的 UV `(0,0) -> (1,1)`，当前不会消费 `UIDrawCommand.uvMin / uvMax`。
+
+## 当前调用锚点
+
+- `tests/Editor/test_xcui_imgui_transition_backend.cpp` 直接覆盖 pending 统计重置和 flush 后 `ImDrawList` 顶点/命令缓冲被写入的行为。
+- `DrawData` 命令模型定义在 [DrawData](../../../UI/DrawData/DrawData.md)。
+- `XCUIDemoRuntime` 头文件声明了一个可能产出 `UIDrawData` 的 demo runtime，但当前代码树里还没有把它真正接到这个 backend 上的调用链。
 
 ## 当前实现边界
 
-- 这是过渡后端，不是最终 XCUI renderer。
-- 当前只覆盖 `FilledRect / RectOutline / Text / Image / PushClipRect / PopClipRect` 六类命令。
-- 所有待刷 draw list 目前都先暂存在 `std::vector` 里，没有增量流式提交。
+- 这是 editor 过渡桥接器，不是完整 XCUI renderer。
+- 当前只覆盖 `FilledRect`、`RectOutline`、`Text`、`Image`、`PushClipRect`、`PopClipRect` 六类命令。
+- 所有待刷数据都先暂存在 `std::vector<::XCEngine::UI::UIDrawList>` 中，没有增量流式提交或跨帧缓存。
 
 ## 相关文档
 

docs/api/XCEngine/Editor/XCUIBackend/XCUIBackend.md

@@ -6,20 +6,29 @@
 
 **源文件目录**: `editor/src/XCUIBackend/`
 
-**描述**: Editor 侧 XCUI 过渡后端，当前主要承接“XCUI draw data 已生成，但最终仍要落到 Dear ImGui / 现有宿主”的桥接层。
+**描述**: Editor 侧 XCUI 过渡后端文档索引。当前源码里这一层只覆盖“已有 `UIDrawData`，但宿主仍是 Dear ImGui”的桥接逻辑，以及一个尚未落地的 demo runtime 声明。
 
-## 当前范围
+## 当前源码范围
 
 - [ImGuiTransitionBackend](ImGuiTransitionBackend/ImGuiTransitionBackend.md)
 - [XCUIDemoRuntime](XCUIDemoRuntime/XCUIDemoRuntime.md)
 
-## 当前定位
+## 与当前源码对齐后的结论
 
-- `ImGuiTransitionBackend` 是当前唯一 source-backed、可直接落到 Dear ImGui `ImDrawList` 的 XCUI 过渡桥接器；当前代码树里已经没有 `XCUIDemoPanel` 这类 demo 面板调用链。
-- `XCUIDemoRuntime` 目前只有头文件声明，还没有 `.cpp` 和真实调用链，更像后续 demo runtime 的占位入口。
+- `editor/src/XCUIBackend/` 当前只有 `ImGuiTransitionBackend.h` 和 `XCUIDemoRuntime.h` 两个头文件，没有额外的 backend `.cpp`。
+- `ImGuiTransitionBackend` 是这里唯一带有明确行为实现、并且被 `tests/Editor/test_xcui_imgui_transition_backend.cpp` 直接覆盖的过渡桥接器。
+- `XCUIDemoRuntime` 仍只有声明，没有 `.cpp`、没有实例化调用链，也没有现役 editor panel 把它接到工作区里。
+- 旧版 `XCUIDemoPanel` 已经不在 `editor/src/panels/` 当前源码树中，因此这里不再保留一个伪装成“现役 panel”的页面入口。
+
+## 文档边界
+
+- 这里记录的是 editor 侧 XCUI 过渡层，不是 XCUI runtime 的完整渲染体系。
+- 若需要查看通用绘制命令模型，应以 [DrawData](../../UI/DrawData/DrawData.md) 为准。
+- 若需要查看现役 editor 工作区面板，应以 [panels](../panels/panels.md) 为准。
 
 ## 相关文档
 
 - [Editor](../Editor.md)
 - [UI](../../UI/UI.md)
 - [panels](../panels/panels.md)
+- [DrawData](../../UI/DrawData/DrawData.md)

docs/api/XCEngine/Editor/XCUIBackend/XCUIDemoRuntime/XCUIDemoRuntime.md

@@ -6,37 +6,40 @@
 
 **源文件**: `editor/src/XCUIBackend/XCUIDemoRuntime.h`
 
-**描述**: XCUI demo runtime 的头文件声明，当前公开输入状态、帧统计、帧结果和一个 move-only 的 PIMPL 运行时类。
+**描述**: XCUI demo runtime 的声明页。当前源码只提供输入/输出结构和一个 move-only PIMPL 类接口，没有对应实现文件。
 
 ## 公开声明
 
 | 声明 | 类型 | 说明 |
 |------|------|------|
-| `XCUIDemoInputState` | `struct` | demo 帧输入，当前覆盖 canvas、指针、焦点与快捷键状态。 |
-| `XCUIDemoFrameStats` | `struct` | 文档就绪、依赖数、元素数、dirty root 数、draw command 数等统计。 |
-| `XCUIDemoFrameResult` | `struct` | `UIDrawData + XCUIDemoFrameStats`。 |
-| `XCUIDemoRuntime` | `class` | move-only PIMPL 声明，公开 `ReloadDocuments()`、`Update()`、`GetFrameResult()`、`TryGetElementRect()`。 |
+| `XCUIDemoInputState` | `struct` | demo 帧输入，覆盖 canvas、指针、窗口焦点和快捷键状态。 |
+| `XCUIDemoFrameStats` | `struct` | 文档就绪状态、依赖数、元素数、dirty root 数、draw list 数、command 数等统计。 |
+| `XCUIDemoFrameResult` | `struct` | `UIDrawData + XCUIDemoFrameStats` 的组合结果。 |
+| `XCUIDemoRuntime` | `class` | move-only PIMPL 接口，声明了 `ReloadDocuments()`、`Update()`、`GetFrameResult()`、`TryGetElementRect()`。 |
 
-## 当前状态
+## 当前源码状态
 
 - 当前工作树里只有 `editor/src/XCUIBackend/XCUIDemoRuntime.h`，没有对应 `.cpp`。
-- 代码搜索也没有发现 `XCUIDemoRuntime` 的真实实例化或调用链。
-- 因此这里公开的构造、析构、移动赋值、`ReloadDocuments()`、`Update()` 和 `TryGetElementRect()` 目前都只是接口声明，不应被文档误写成已完成实现。
+- 代码搜索没有发现 `XCUIDemoRuntime` 的真实实例化、工作区接线或测试覆盖。
+- 因此这里应被视为 declaration-only 的预留接口，而不是已经落地的 demo runtime 实现。
 
-## 当前语义边界
+## 从头文件可以确认的事实
 
-- 从头文件能确认的事实只有：
-  - 它采用 `RuntimeState` PIMPL
-  - 它是 move-only，禁止拷贝
-  - 它打算围绕“输入 -> 帧结果 -> 元素矩形查询”组织 demo runtime
-- 但当前无法从源码确认：
-  - 文档加载策略
-  - 实际 draw data 生成过程
-  - 焦点 / hover / command 跟踪逻辑
-  - 失败返回路径
+- 运行时内部状态通过 `RuntimeState` PIMPL 隐藏。
+- 类型支持移动构造和移动赋值，显式禁止拷贝。
+- `Update(...)` 的接口形态表明它计划围绕“输入状态 -> 帧结果”组织运行时。
+- `TryGetElementRect(...)` 说明设计上预留了按元素 id 查询布局矩形的能力。
+
+## 当前无法从源码确认的部分
+
+- 文档/依赖的加载来源和刷新策略。
+- `UIDrawData` 的实际构建过程。
+- 焦点、hover、命令触发与 `lastCommandId` 等统计字段的更新逻辑。
+- 出错路径、空文档行为以及线程/生命周期约束。
 
 ## 相关文档
 
 - [XCUIBackend](../XCUIBackend.md)
+- [ImGuiTransitionBackend](../ImGuiTransitionBackend/ImGuiTransitionBackend.md)
 - [DrawData](../../../UI/DrawData/DrawData.md)
 - [Types](../../../UI/Types/Types.md)

docs/api/XCEngine/UI/DrawData/DrawData.md

@@ -43,7 +43,7 @@
 - `tests/Editor/test_xcui_draw_data.cpp` 当前直接验证 `UIDrawList` 的命令顺序、payload 保真和 `UIDrawData` 的多列表聚合计数。
 - `editor/src/XCUIBackend/ImGuiTransitionBackend.h` 当前是最直接的消费端，把 `PushClipRect` / `PopClipRect` / `Text` / `Image` 等命令映射到 ImGui。
 - `engine/src/UI/Runtime/UIScreenDocumentHost.cpp` 当前在 UI runtime 渲染阶段创建 draw list，并把 `drawListCount`、`commandCount` 统计写回运行结果。
-- `new_editor/src/Shell/UIEditorPanelFrame.cpp` 和多组 editor integration 测试当前直接构建 `UIDrawList`；旧版 `editor/src/panels/XCUIDemoPanel.cpp` 已不在当前代码树中。
+- `new_editor/src/Shell/UIEditorPanelFrame.cpp` 和多组 editor integration 测试当前直接构建 `UIDrawList`；`editor/src/panels/` 下已经没有旧版 `XCUIDemoPanel` 这类 XCUI demo 面板，相关遗留说明应以 [Editor/XCUIBackend](../../Editor/XCUIBackend/XCUIBackend.md) 为准。
 
 ## 相关文档