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

# NewEditor Window Workspace Single-Source Refactor Plan

Date: 2026-04-22
Status: In Progress

## Progress

Completed on 2026-04-22:

1. `EditorWindowWorkspaceCoordinator::BuildWorkspaceMutationController()` no longer reads mutation input from `EditorWindowWorkspaceStore` mirror
2. mutation input is now built from live `EditorWindow` controllers at call time
3. Debug build of `XCUIEditorApp` passed
4. manual verification passed for:
   - detach
   - re-dock
   - open / close baseline behavior
   - detached title baseline behavior

Next:

1. split detached title refresh from frame-time projection
2. then remove the remaining per-frame mirror commit path
## 1. Objective

这份计划只处理 `new_editor` 当前最严重的一处结构性冗余:

1. 每个 `EditorWindow` 已经各自持有一份 live `UIEditorWorkspaceController`
2. `EditorWindowWorkspaceStore` 又额外持有一份完整的 `UIEditorWindowWorkspaceSet`
3. 宿主层每帧把前者整份投影回后者
4. 跨窗口操作再从后者反向重建 controller 灌回窗口

本计划的目标不是“看起来更抽象”，而是把窗口 workspace 的单一事实源收回到 live window，自根源消除双写状态同步环，同时不破坏以下现有行为:

1. 分离窗口打开与关闭
2. Tab 跨窗口拖拽
3. 面板 detach / re-dock
4. detached tool window 标题与尺寸策略
5. 现有 `UIEditorWindowWorkspaceController` 上的跨窗口变换语义

## 2. Confirmed Problem

当前重复链路已经形成完整闭环:

1. live state:
   - `EditorWindowRuntimeController::m_workspaceController`
2. mirrored state:
   - `EditorWindowWorkspaceStore::m_windowSet`
3. frame-time projection:
   - `EditorWindowHostRuntime::RenderAllWindows(...)`
   - `EditorWindowWorkspaceCoordinator::CommitWindowProjection(...)`
4. mutation-time reverse application:
   - `EditorWindowWorkspaceCoordinator::BuildWorkspaceMutationController()`
   - `EditorWindowWorkspaceCoordinator::SynchronizeWindowsFromWindowSet(...)`

这不是普通 cache，而是双向同步的第二套真相源。

## 3. Root Cause

根因不在某一个函数，而在宿主层把“跨窗口协调”实现成了“跨窗口状态镜像”。

当前设计默认:

1. window 内的 live controller 负责真实交互与更新
2. store 内的 window set 负责跨窗口 mutation 的输入
3. 二者通过每帧投影保持近似一致

这导致:

1. 同一语义的 workspace/session 状态有两份 owner
2. 每帧发生整份复制和整套验证
3. mutation 逻辑被迫依赖 mirror，而不是直接面向 live windows
4. 标题刷新、窗口集合描述、关闭路径，也被顺带绑在 mirror 上

## 4. Why This Is The Most Serious Redundancy

这处问题同时命中四个严重特征:

1. 同一职责重复实现
   - live window controller 和 mirrored window set 都在表达同一份窗口 workspace 状态
2. 同一帧重复计算
   - 每帧 `CommitWindowProjection(...)` 都会复制 `m_windowSet`、覆写某个窗口状态、再验证整套 window set
3. 结构扩散
   - 打开窗口、关闭窗口、跨窗口拖拽、标题刷新都被迫围绕 mirror 组织
4. 没有独立 owner
   - `EditorWindowWorkspaceStore` 并没有独立业务语义，只是在宿主层替 live state 保存一份副本

## 5. Red Lines

这次重构明确禁止以下做法:

1. 只删除 `CommitWindowProjection(...)`，但继续让 mutation 从旧 store 读数据
2. 先删 store，再临时把跨窗口逻辑散落回 `EditorWindowWorkspaceCoordinator`
3. 改写 `UIEditorWindowWorkspaceController` 的跨窗口变换语义
4. 修改 dock / transfer / extract 的业务规则，只为了配合结构调整
5. 以“后面再补验证”为理由跳过 detached window / global tab drag 的回归验证

其中第 1 条最危险。它一定会造成功能回归，因为当前 detached 窗口标题刷新和 mutation 输入都还绑在 projection 路径上。

## 6. Target End State

目标终态必须满足:

1. live `EditorWindow` 持有的 `UIEditorWorkspaceController` 成为唯一可变真相源
2. 跨窗口 mutation 需要的 `UIEditorWindowWorkspaceSet` 改为按需从 live windows 现采样构建
3. `EditorWindowWorkspaceStore` 不再保存整份 `workspace/session`
4. detached 窗口标题刷新从 projection 逻辑中独立出来
5. primary / active / existing window 集合信息只保留真正被消费的最小元数据

允许两种落地形式:

1. 保留 `EditorWindowWorkspaceStore`，但只保留窗口元数据和注册信息，不再保存 workspace/session
2. 完全删除 `EditorWindowWorkspaceStore`，由 coordinator 直接从 host runtime 构建 snapshot

## 7. Refactor Strategy

### Phase A. Freeze semantics and add live snapshot builder

先新增从 live windows 构建 `UIEditorWindowWorkspaceSet` 的单一路径，例如:

1. `BuildLiveWindowWorkspaceSnapshot()`
2. 或 `BuildWorkspaceMutationControllerFromLiveWindows()`

要求:

1. snapshot 必须完整覆盖所有活跃窗口
2. 每个窗口的 workspace/session 直接来自 live controller
3. primary window id 必须来自 live host state
4. active window id 只保留当前真实需要的最小语义

这一步先增加，不删旧路径。

### Phase B. Make mutation read from live snapshot instead of store mirror

把以下入口改为依赖 live snapshot:

1. `BuildWorkspaceMutationController()`
2. `TryStartGlobalTabDrag(...)`
3. `TryProcessDetachRequest(...)`
4. `TryProcessOpenDetachedPanelRequest(...)`
5. cross-window drop commit path

要求:

1. mutation 前只从 live windows 取状态
2. mutation 后仍复用 `SynchronizeWindowsFromWindowSet(...)` 回灌窗口
3. 在这一阶段仍允许 store 暂时存在，但不能再是 mutation 输入源

### Phase C. Split title refresh from projection

当前 `RefreshWindowTitle(...)` 被挂在 `CommitWindowProjection(...)` 后面，这是一种错误耦合。

必须单独拆出标题同步路径:

1. detached 窗口标题直接基于 live controller 刷新
2. 标题刷新继续允许 frame-time 执行
3. 但标题刷新不能再隐含 workspace mirror commit

完成后，删除“为了标题而保留每帧 projection”的借口。

### Phase D. Remove mirrored workspace/session from store

在 mutation 输入已经切换到 live snapshot 后:

1. 删除 `EditorWindowWorkspaceStore` 中的 `workspace/session` 镜像
2. 删除 `BuildWindowState(...)` 这类整份复制逻辑
3. 删除每帧 `CommitWindowProjection(...)`
4. 删除围绕 projection 的整套验证与回退路径

如果此时 store 还存在，它只能保存:

1. 已注册窗口 id
2. primary window id
3. 可能仍有意义的轻量元数据

## 8. Functional Risk Analysis

这次重构不是零风险，但风险集中且可控。

### 8.1 Real risk: title synchronization

如果直接删除每帧 projection，而不拆标题刷新:

1. detached 窗口标题可能停留在旧 active panel
2. 同一窗口内切 tab 后标题可能不再更新

因此标题刷新必须先和 projection 解耦，再删 projection。

### 8.2 Real risk: mutation input staleness

如果 mutation 仍从 store 读状态，而 store 不再每帧同步:

1. detach 可能从旧 workspace 提取 panel
2. cross-window drop 可能基于过期 session 判断 panel owner
3. open detached panel 可能错误判断某 panel 已经打开或未打开

因此必须先引入 live snapshot builder，再切 mutation 输入。

### 8.3 Medium risk: lifecycle and close path assumptions

当前 `IsPrimaryWindowId(...)`、`DescribeWindowSet()`、`RemoveWindowProjection(...)` 都依赖 store。

需要逐条确认:

1. 哪些只用于日志
2. 哪些只用于关闭路径
3. 哪些真影响行为

如果不区分，容易把“日志依赖”误当成“结构依赖”。

### 8.4 Low risk: cross-window mutation algorithm itself

`UIEditorWindowWorkspaceController` 和 `UIEditorWorkspaceTransfer` 负责的是跨窗口 panel 变换语义。

本计划不改:

1. extract 规则
2. insert 规则
3. dock 规则
4. detached workspace 生成规则

因此只要 mutation 输入快照正确，这一层不是主要风险源。

## 9. Why This Refactor Is Actually Simplifying

它不是表面简化，而是实质上减少状态 owner。

完成后会得到:

1. 窗口 workspace 只在 live window 内持有一份
2. mutation 输入不再依赖长期镜像，而是按需快照
3. frame path 不再做整份 workspace/session 复制与整套 validate
4. coordinator 的职责变成:
   - 从 live windows 取快照
   - 调用 mutation controller
   - 把 mutation 结果同步回 live windows
5. title refresh 变成一个独立的小职责，而不是夹带在 projection 里

也就是说，复杂度不是被藏起来，而是真的减少了一层。

## 10. Why This Refactor Is Root-Cause-Oriented

它之所以是从根源出发，是因为它处理的是“谁拥有窗口 workspace 真相”。

如果不解决 owner 问题，只做局部删减，最终都会回到:

1. 某处还需要一份 mirror
2. 某帧还得再同步一次
3. 某条宿主功能又悄悄绑回 projection

而这份计划直接把真相源收回 live window，把跨窗口 controller 降级为临时 snapshot consumer，这才是对根因动刀。

## 11. Validation Requirements

没有以下验证，不允许落地删除 projection:

1. detached window 内切换 active panel 后，窗口标题实时更新
2. primary window detach panel 正常创建新窗口
3. detached window 再次拖拽 panel 发起 global tab drag 正常
4. 跨窗口 drop 到 tab stack 和 relative dock 都正常
5. 已打开 tool window 的 panel 重复打开请求仍然正确复用
6. 关闭 detached window 后，其余窗口状态保持正确
7. 关闭 primary window 时，其他窗口生命周期不异常
8. `XCUIEditorApp` Debug 构建通过

## 12. Completion Criteria

只有满足以下条件，这次重构才算真正完成:

1. `EditorWindowWorkspaceStore` 不再持有整份 `workspace/session` 镜像
2. `EditorWindowHostRuntime::RenderAllWindows(...)` 不再每帧调用 workspace projection commit
3. 所有跨窗口 mutation 都从 live snapshot 构建输入
4. detached 标题刷新与 projection 彻底解耦
5. 现有 detach / drag / re-dock / close 行为无回归

## 13. Final Statement

这次重构不能靠“删几行同步代码”完成。

真正安全、真正彻底的路径只有一条:

1. 先建立 live snapshot 输入
2. 再把 mutation 输入切过去
3. 再拆标题刷新
4. 最后删除 mirror

只有按这个顺序，才能既不破坏功能，又从根上消灭这套双写宿主残片。