合并远端 master 更新

保留远端 UI 编辑器与门禁清理改动

合入本地 AGC 直连 Codex 长任务修复

# Conflicts:
#	apps/ai-game-creator-shell/package-lock.json
#	apps/ai-game-creator-shell/src-tauri/Cargo.lock
#	apps/ai-game-creator-shell/src/view/project-development/index.tsx
#	apps/ai-game-creator-shell/tests/appSurface/home.suite.ts

docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md

@@ -0,0 +1,16 @@
+# UI 编辑会话模块边界
+
+更新时间：`2026-08-19`
+
+`apps/ai-game-creator-shell` 的 UI 编辑器以 `useUiEditorSession` 作为视图与 adapter 的唯一协调边界。会话持有资源加载、revision、预览请求、选择、节点可见性、步骤 gate、异步操作和保存意图；`UiDesignStateStore` 与 Tauri 调用仍由该模块注入，不进入视图组件。
+
+页面与子视图不得再传递完整 controller。它们按职责读取以下小 projection：
+
+- `input`：资源输入、节点树及调试操作。
+- `canvas`：当前画布、选择、聚焦与节点变换。
+- `inspector`：当前检查对象及其编辑动作。
+- `workflow`：步骤 gate 与正式 AI 操作生命周期。
+- `dialogs`：导入、清空和删除确认。
+- `save`：加载 / revision 状态、脏状态、保存警告和保存意图。
+
+预览树在会话边界归一化为 `UITree | null`：尚未选择界面图、正在加载或尚未识别树时均以 `null` 表示，不能把 `Array.find` 的 `undefined` 传播到视图接口。

docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md

@@ -54,10 +54,10 @@
 - 普通图片与角色在 provider 回图后先按统一业务像素矩阵尝试交付尺寸归一：允许无放大恢复时使用 Lanczos 重采样并居中裁切，无法安全恢复时保留 provider 实际尺寸并返回非阻断告警。普通图片随后以这张实际交付尺寸图同时作为网格分析源和 RGBA 采样源；角色先持久化同尺寸平底原图并交给 BgFilter，正常成功后把 Alpha 蒙版回贴到该平底原图，再以平底原图分析网格、以透明 RGBA 图采样。图标仍以已持久化的平底 provider 图尺寸为基准，BgFilter 成功并回贴 Alpha 后执行同样的双输入规整。固定首版参数为：分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、相邻边缘峰间距使用线性插值 `P30` 估算步长、固定色板关闭、K-means 最大采样 `262144`。
 - 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均按像素后处理失败的 best-effort 规则保留进入该步骤前的图片。
 - 单格颜色按 `Σ(A × RGB) / ΣA` 进行 Alpha 加权；单格覆盖率按 `Σ(A / 255) / N` 计算。覆盖率大于等于 `0.375` 且 `ΣA > 0` 时输出硬 Alpha `255`，否则输出严格的 `[0,0,0,0]`；最终 Alpha 只允许 `0 / 255`。分析用 16 色只负责网格识别，不限制最终输出色数。
-- 逻辑低分辨率图只存在于内存；snapper 在规整内部使用 nearest 恢复到当前 RGBA 输入尺寸，并直接替换原本即将持久化的最终图片字节。普通图片和角色的该输入已经过前置 Lanczos 交付尺寸归一，或在无法安全归一时保留 provider 实际尺寸；图标输入以已持久化平底原图的实际尺寸为准。nearest 不替代前置尺寸归一，规整完成后不再执行第二次 Lanczos 或其它尺寸恢复。角色和图标应复用 Alpha 回贴阶段已经读取的平底原图；确需重新读取时，最多增加一次对已有 provider 对象的 OSS GET，不得新增 OSS PUT。
+- 逻辑网格图只存在于 snapper 内存；采样后按单一整数倍 nearest 放大到最接近规整输入的尺寸，再编码为唯一最终 PNG。横纵共用同一 N，保持逻辑图宽高比，禁止非整数拉回精确源尺寸、补边、裁切或 Lanczos / bilinear。普通图片和角色的规整输入已经过前置 Lanczos 交付尺寸归一，或在无法安全归一时保留 provider 实际尺寸；图标输入以已持久化平底原图的实际尺寸为准。整数倍放大不替代前置尺寸归一，规整完成后不再执行第二次尺寸插值。角色和图标应复用 Alpha 回贴阶段已经读取的平底原图；确需重新读取时，最多增加一次对已有 provider 对象的 OSS GET，不得新增 OSS PUT。
 - 像素模式的持久化增量必须为零：普通图片仍只上传原有一张最终主图；角色仍只保留原有 provider 原图与透明主图；图标仍只保留原有 provider 原图、透明图集和实际成功的切片。禁止保存逻辑低分辨率图、像素化前后双份主图、预览图、网格诊断图或报告，禁止新增 asset / resource 类型、项目资源、画布 item、队列 job kind 或数据库字段。
 - 像素后处理属于 best-effort：失败时保留进入该步骤前的图片，继续原有最终上传与画布完成，并通过既有通用 `warning` 返回非阻断原因，不把任务改为失败或退款。BgFilter 自身失败时仍按原 source-only fallback 收口，像素处理不运行；图标后处理成功后再执行原有自动拆分，拆分告警继续使用现有 `sliceWarning` 语义。
-- 选中已有静态栅格图层后的 `完美像素` 是独立的一键派生操作，不等同于生成请求上的 `style="pixelArt"`。它不打开参数面板，只处理当前活动图层，保留源图，并在源图右侧创建同尺寸 PNG 派生结果；音频、视频、图片序列和 `character-animation` 不显示该按钮。
+- 选中已有静态栅格图层后的 `完美像素` 是独立的一键派生操作，不等同于生成请求上的 `style="pixelArt"`。它不打开参数面板，只处理当前活动图层，保留源图，并在源图右侧创建整数倍放大后的 PNG 派生结果；该 PNG 宽高比等于逻辑图，尺寸接近但不保证等于源图；音频、视频、图片序列和 `character-animation` 不显示该按钮。
 - 完美像素、手动去背景、裁扩和所有图集切片是确定性派生操作，分别保存 `image.perfect-pixel`、`image.remove-background`、`image.crop-expand`、`spritesheet.split` 的 V2 `generationInputs`。四者固定 `fields: []`；存在正式来源资源 / 素材行时只保存服务端权威的 `references[id="source"]`，引用仅用于来源溯源，不是算法参数或可编辑槽位，没有正式行时保存空数组。改造 capability 使用独立 allowlist，四者及历史 `pixel-art-snap-*` 结果永不允许改造；自动切片的 source 是实际被切的透明图集，整张生成图集仍保留原生成 action。
 - 裁扩创建资源时，未携带 `sourceResourceId` 仍允许保存无正式来源引用的确定性结果；一旦携带该 ID，api-server 必须确认它属于当前 owner 和当前项目，否则以 `400` 拒绝，禁止同时持久化悬空 / 越权 `sourceResourceId` 和空来源配方。
 - 已有图片像素规整固定调用登录态同源 `POST /api/editor/images/pixel-art-snaps`，复用同一纯内存 Rust snapper、CPU 并发许可和输入尺寸上限。该入口免费、只走当前 HTTP 请求内的 inline 处理，不创建 `external_generation_job`，不刷新或自动打开任务侧栏，也不进入泥点扣费 / 退款链路。它另有一层端点级并发闸（最大 4、等待队列上限 2048），设在首次 IO 之前；队列满返回 `503` 并带 `Retry-After`，等待超预算返回 `504`。30 秒总预算从 handler 入口起算，覆盖归属校验的 SpacetimeDB 读取、OSS 下载、两层排队与规整，不是只算 CPU 部分。
@@ -67,9 +67,9 @@
 - B 层的边界是可验证的、且已确认只服务完美像素：`requiresLiveSession: true` 全仓仅有一处置位（完美像素提交路径），`claimActiveInlineGenerationDialog` / `releaseActiveInlineGenerationDialog` / `hasActiveInlineGenerationDialog` 的全部五个调用点也都在完美像素的提交、重试与恢复上。直接体量：`perfectPixelOperationStore.ts` 203 行（测试 228 行）、`useInlineGenerationPlaceholderExpiry.ts` 140 行（测试 401 行）、`hydratePerfectPixelOperation` 128 行，加上工作流里的恢复 effect 与窗口锚定，生产代码约 1100 行、测试约 2500 行（后两个数字是估算，前面几个是实测）。同为免费、同步、无 durable job 的手动图集拆分只用约 85 行客户端代码（失败即报错，`taskId` 用随机 UUID，无幂等、无对账），是本仓库对同类问题的既有廉价答案；完美像素额外的 B 层是**特例而非范式**，不得据它给其它链路加同样的机制。
 - 前端提交前先创建关闭 composer 的右侧生成占位，再解析或上传源图以取得稳定引用，随后把版本化 `perfectPixelOperation` 请求快照写入**本机账本**（占位本身只带 `perfectPixelOperationId` 标记）并 flush 当前项目布局，最后才发送 POST。`canvasCompletion.dialogId` 同时作为 operation identity、稳定 task identity 的输入和本地源图上传 ID；同一 operation 的上传路径与后续 POST 请求都不得随机漂移。`sourceImageSrc` 优先由当前图层已有的 `objectKey / resourceId / sourceAssetId` 解析；尚未登记的浏览器本地图片只执行 `ticket → OSS PUT → confirm → objectKey`，不为这条持久化输入换取 signed URL。一个 `AbortSignal` 必须贯穿源文件 fetch / 图片解析边界、ticket、PUT、confirm，完整上传 helper 的可选换签也必须透传同一 signal。正式请求不得包含 `data:` / `blob:`、signed URL 或普通外链。后端在读取源图前必须把该字段解析为当前 owner 已登记的私有 OSS object key，并核对 project / resource / asset 归属。
 - 源准备与 operation journal 使用两段绝对预算：`ticket → PUT → confirm` 连同源解析共用 90 秒；confirm 成功后形成稳定 `perfectPixelOperation` 并**同步写入本机账本**（`perfectPixelOperationStore`，owner + project 双键的 localStorage），布局里只留 `perfectPixelOperationId` 标记。原先的 strict layout save 通道（60 秒绝对预算、revision ACK 前 POST 为零）已整体删除：账本不再寄生在用户布局上，本机写入不过网络也不受服务端校验影响，同样能保证请求可被追溯。被解除的是**客户端侧**「拿不到 revision ack 就拒发」这一层阻断；端到端依赖仍在——布局 PATCH 被校验拒绝、占位因此从未落库时，POST 仍会被服务端以 409 拒收。POST 前仍然 `await` 一次 best-effort 布局保存——服务端要求占位**此前已经持久化**，否则 `validate_editor_pixel_art_snap_placeholder_exists` 直接 409；但 best-effort 不再提供成功 ACK，因此客户端**无法证明**该前置已满足，只能提高满足它的概率（占位可能已由此前的自动保存落库，PATCH 也可能成功而 ACK 丢失）。该 flush 没有整体上限，所以 75 秒对账窗口必须在 flush 返回、authority 复核通过之后才锚定，且首次提交与人工重试同此口径；锚定只覆盖 `submittedAt / reconcileUntil`，按同一 `operationId` 覆盖账本，request 与 dialog / operation / task identity 逐字节不变。此阶段失败持久化为 `failed + perfectPixelOperation`，保留同一 `sourceImageSrc / dialogId / taskId / request`；重试请求必须与账本中的 POST JSON byte-for-byte 一致且不得重新上传。**明确接受的行为，不是缺口**：占位恢复可删除之后，用户删掉未收口占位再从源图发起会得到第二个 identity，旧的服务端操作若迟到落库就会多出一份素材，两个 `taskId` 无法幂等合并。按上文的优先级判据，这属于「已生成资源丢失关联」而非主链路故障，代价是用户自行删掉多余素材，**不得**通过让本机账本参与防重来「闭合」——那是被明令禁止的「禁止一张图处理两遍」。confirm 成功后浏览器在 operation 首次 PATCH 落库前立即崩溃仍可能留下 object-only 记录；完全消除该窗口需要服务端 durable upload journal，不属于当前前端修复。
-- 该已有图片入口使用 strict 语义：只接受静态 PNG / JPEG / WebP，GIF、APNG、动画 WebP、图片序列及其它非静态媒体必须在处理前拒绝。strict 与生成风格复用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码；仅当横纵两轴都未检测到步长、legacy 即将使用 `min(width,height)/64` 统一网格兜底时拒绝。任一轴已检测到步长时，两条路径行为和输出必须一致。源图读取、解码、尺寸校验、排队、像素规整或 PNG 编码任一步失败 / 超时 / 不适用时，请求失败，不保留原图副本冒充成功，不执行最终 OSS PUT，也不创建 project resource、账号素材或结果图层。成功时只对唯一的逻辑分辨率 PNG 执行一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`，再按 `canvasCompletion` 写回一个派生图层；resource、asset、响应与图层使用该 PNG 的实际宽高，不要求与源图或占位尺寸相等，也不得另存输入尺寸恢复版、诊断图或前后对比图。
+- 该已有图片入口使用 strict 语义：只接受静态 PNG / JPEG / WebP，GIF、APNG、动画 WebP、图片序列及其它非静态媒体必须在处理前拒绝。strict 与生成风格复用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码；仅当横纵两轴都未检测到步长、legacy 即将使用 `min(width,height)/64` 统一网格兜底时拒绝。任一轴已检测到步长时，两条路径行为和输出必须一致。源图读取、解码、尺寸校验、排队、像素规整或 PNG 编码任一步失败 / 超时 / 不适用时，请求失败，不保留原图副本冒充成功，不执行最终 OSS PUT，也不创建 project resource、账号素材或结果图层。成功时只对唯一最终 PNG 执行一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`，再按 `canvasCompletion` 写回一个派生图层；该 PNG 是逻辑网格经整数倍 nearest 放大后的结果，宽高比等于逻辑图，尺寸接近但不保证等于源图或占位；resource、asset、响应与图层使用该 PNG 的实际宽高，也不得另存未放大的逻辑图、输入尺寸恢复版、诊断图或前后对比图。
 - strict 的本次结果事实零写入边界截至首个最终 PNG PUT：所有可预判的引用、归属、类型、静态编码、元数据、网格适用性和 CPU 处理错误必须在此前失败；前置 owner-scoped 项目 / 素材读取仍可能按既有语义懒建默认 canvas / folder，这些基础记录不属于本次完美像素结果。后端先纯计算精确 object key 和候选 project resource，再调用只读 SpacetimeDB preflight 校验自定义素材目录归属、复用权威 completion planner，并执行 legacy / structured 的 2 MiB 总量与 512 KiB 单项门禁；默认目录尚未创建时允许通过，preflight 不写库。preflight 与 PUT / HEAD / 原子 persist 共用 60 秒绝对 deadline；preflight 失败或超时不得 PUT，也不得带 `resultPersistenceStarted`。最终 PNG 的 OSS PUT / HEAD 位于数据库事务外；验证上传结果后，asset object、project resource、账号素材与可选 canvas completion 由单个受 runtime service identity 保护的 SpacetimeDB procedure 在一次事务中原子提交，并重新校验目录、布局、幂等身份与 revision。preflight 不加锁或 reservation，所以通过后若目录或画布并发漂移，最终事务仍可能在 PUT 后拒绝并留下 OSS 孤儿对象；这是本次最小修复明确保留的 TOCTOU 边界。operation 以 `owner + project + canvasCompletion.dialogId` 为作用域，task / object / resource / asset ID 稳定派生，object key 携带规范请求与输入 / 输出摘要形成的 fingerprint；一旦 owner-scoped 项目快照已发现同 operation 的稳定 resource，本次 POST 不再执行 candidate-key exact replay，而是直接返回 `operationResultAlreadyExists=true` 并交由 GET 对账；输入漂移或部分既有事实失败关闭。HTTP timeout/drop 不能撤销已发往远端的 procedure，客户端仍须按稳定 `taskId / objectKey / resourceId` 对账，不能把未收到回包等同于未提交。
-- 手动入口的算法指纹随逻辑分辨率输出升级为 `perfect-pixel-v2`。在完成请求基础校验、owner-scoped 项目读取与占位验证后，只要同一稳定 `resourceId` 已存在，后端必须在来源解析、OSS GET、像素规整、candidate object key、preflight 与 OSS PUT 前返回 `409 + operationResultAlreadyExists=true`，并携带已鉴权的稳定 `resultResourceId`；不再按 candidate object key 继续 exact replay。前端 initial 与 retry 两条 catch 都按稳定资源与 task GET 项目对账，由权威快照明确 `applied`、`dialog-missing` 或 `conflict`；即使稳定记录的 `taskId` 损坏，也必须据 `resultResourceId` 找到该记录并失败关闭为冲突，不得持续等待。该标记表示旧权威结果已存在，不得与“本次 PUT 已开始”的 `resultPersistenceStarted` 混用；发布时仍须排空旧算法实例以规避独立新操作在 preflight 到提交之间的跨版本 TOCTOU。
+- 手动入口的算法指纹随整数倍接近原图放大升级为 `perfect-pixel-v3`。在完成请求基础校验、owner-scoped 项目读取与占位验证后，只要同一稳定 `resourceId` 已存在，后端必须在来源解析、OSS GET、像素规整、candidate object key、preflight 与 OSS PUT 前返回 `409 + operationResultAlreadyExists=true`，并携带已鉴权的稳定 `resultResourceId`；不再按 candidate object key 继续 exact replay。前端 initial 与 retry 两条 catch 都按稳定资源与 task GET 项目对账，由权威快照明确 `applied`、`dialog-missing` 或 `conflict`；即使稳定记录的 `taskId` 损坏，也必须据 `resultResourceId` 找到该记录并失败关闭为冲突，不得持续等待。该标记表示旧权威结果已存在，不得与“本次 PUT 已开始”的 `resultPersistenceStarted` 混用；发布时仍须排空旧算法实例以规避独立新操作在 preflight 到提交之间的跨版本 TOCTOU。
 - `POST /api/editor/images/pixel-art-snaps` 是有副作用的 unsafe POST。客户端不得为它配置 `EDITOR_REQUEST_RETRY_OPTIONS`，请求字节可能已发出后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放；Bearer 中间件在 handler 前以 `401` 拒绝、刷新 token 后的既有认证恢复不属于业务副作用重放，保持通用行为。POST 回包中的 `project / resource / asset` 不是结果 verdict；首次成功回包、未知异常、人工 exact replay 和刷新恢复都只读取项目 GET。`perfectPixelOperation.submittedAt / reconcileUntil` 在 pre-POST flush 返回、authority 复核通过之后、POST 发出之前建立统一 75 秒绝对窗口（该 flush 没有整体上限，锚在它之前会让窗口在请求发出前就烧光），POST 回包不能续期；读取必须立即执行一次，随后退避间隔不超过 5 秒，窗口已过期时仍执行一次即时 GET。每次项目读取使用 `requestJson.deadlineAt` 覆盖缺 token 补票、业务 fetch、401 refresh、重试退避与响应体读取；窗口内单次最多 10 秒且不得越过 `reconcileUntil`，过期后的唯一即时读取最多额外 10 秒。固定判据为：匹配 task 的唯一 resource 加已收口 dialog / 关联图层才是画布成功；dialog 不存在但存在匹配 task resource 才是 asset-only 成功；dialog 仍 generating、dialog 不存在且无匹配 resource、项目始终不可读或窗口耗尽均保持 unknown。素材库刷新只在项目终态后 fire-and-forget，同步抛错、异步拒绝或永久挂起都不得阻塞 verdict、项目快照应用和执行锁释放。
 - unknown 状态持久化为原 generation dialog 上的 `pending-confirmation + perfectPixelOperation`（账本在本机，布局只留 `perfectPixelOperationId`）。**用户可以随时删除该占位**，任何状态都不例外、也不弹确认：删除不撤销任何在途请求，结果照常落库并进素材库，服务端发现 dialog 已不在会返回 `DialogMissing`；封锁用户删除自己画布上的元素不是可接受的代价。删除后**结果不再自动回填画布**（服务端发现 dialog 已不在会返回 `DialogMissing`），这是用户主动放弃的结果，不得判定为缺陷；但对账本身不会因此停止——当前标签页已经在飞的 Promise 会继续读到终态，本机账本也会以孤儿身份在下次加载被读一次，结果确已落库时仍会提示用户去素材库取。未删除时用户可继续 GET 对账或显式按原 identity 重放。人工重试在 pre-POST flush **之后**才刷新观察窗口（同上一节的锚定口径），POST JSON 必须与持久请求 byte-for-byte 一致，不得按当前画布、目录、类型或标题重建，也不得创建第二个 dialog / task / object / resource / asset。hydrate 后只做 GET，不自动 POST、上传或重建请求。处理成功但事务内权威 dialog 已删除时，后端保留 object / resource / asset 并返回 asset-only 事实，canvas / revision 不变；前端只有在项目 GET 看见匹配 task resource 后才能提示“已保存到素材库”。现有布局 CAS 没有 deletion tombstone，completion 与其它已持久化布局编辑冲突时继续按权威 revision 守卫收口；尚未防抖落库的本地编辑合并不在本批范围。
 - 删除 generation dialog 的按钮、快捷键和右键菜单必须在写画布历史、清选择或执行低层移除前经过同一请求保护入口。未收口完美像素 operation 与其它占位同样可被立即删除，写正常的 `delete-generation-result` 历史并清理 identity；删除确认只对**计费**生成成立（现成弹窗讲的是「已消耗的泥点不会返还」，而完美像素 `generation_cost_mud_points = 0`），判据收敛为具名的 `requiresGenerationDeleteConfirmation`。低层 `removeCanvasGenerationDialogById` 必须无条件删除——低层对上层抗命正是「占位未删却写出伪历史」的根因。
@@ -182,7 +182,7 @@
 - 生成图片点击后显示画布内 `Image Generator` 占位框和跟随占位框的生成输入框，生成失败保留占位和输入状态，生成成功后在占位位置创建真实图层，并让输入框继续跟随该生成图。
 - 选择 `1K / 2K` 或切换比例后，占位框在待生成和生成中阶段都必须立即显示对应目标像素尺寸；从普通图片、角色、图标图集或 UI 设计图进入改造时同样适用，完成落图前后不得从默认 1K 框跳变为 2K 成品。
 - 普通图片、角色和图标面板显示 `像素艺术` 勾选项并正确提交 / 恢复 `style: "none" | "pixelArt"`；其它生成或编辑面板不显示该选项。旧 payload、未知字符串、不支持 `kind` 和非字符串输入分别按本方案约定的兼容或错误语义处理。
-- `pixelArt` 输出 Alpha 只包含 `0 / 255`；普通图片和角色先完成 Lanczos 交付尺寸归一，再由 snapper 使用 nearest 把逻辑网格恢复到同一输入尺寸，规整后不得再次执行尺寸插值。成功和后处理失败两条路径都不得比 `none` 增加 OSS PUT、项目资源、账号素材或画布 item，逻辑低分辨率图不得出现在 OSS 或响应资源快照中。
+- `pixelArt` 输出 Alpha 只包含 `0 / 255`；普通图片和角色先完成 Lanczos 交付尺寸归一，再由 snapper 按整数倍 nearest 放大到最接近该输入的尺寸，规整后不得再次执行尺寸插值。成功和后处理失败两条路径都不得比 `none` 增加 OSS PUT、项目资源、账号素材或画布 item，未放大的逻辑网格图不得出现在 OSS 或响应资源快照中。
 - 生成中的占位图聚焦后支持键盘 `Delete` / `Backspace` 删除，不新增可见删除按钮；删除后对应异步回写必须按生成器 ID 判空并丢弃，不能把已删除素材重新落回画布。音乐 / 音频生成占位和已生成音频图层同样必须支持键盘删除。
 - 画布常用快捷键必须与右上角快捷键弹窗一致；新增快捷键时应同步更新 `ImageCanvasShortcutModel`、快捷键 hook 单测和本方案。输入框、文本域和 contenteditable 聚焦时不得触发画布编辑快捷键。
 - 撤销或恢复画布布局时不得覆盖同 ID 生成对象当前的任务生命周期、提示词、参考图和结果；上传持久化延迟回填内部资源 ID 不得把安全移动误判为素材替换。生成结果必须在加入画布前写入生成历史，自动适合视图不得覆盖这条栈顶记录。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -1,5 +1,75 @@
 # AI 游戏创作智能体 App 实施计划
 
+## 2026-08-19 UI Editor 节点右键菜单
+
+## 2026-08-20 UI Editor 最终预览互斥子节点
+
+最终预览中，选中一个 `Exclusive` 父节点时，它的子节点切换条必须在该父节点自身的预览坐标空间内、紧贴节点上方悬浮；不得固定在预览容器左上角，也不得另行按屏幕坐标换算。点击 tab 必须显式选中对应子节点，不能按通用“切换可见性”语义把当前分支隐藏。`Exclusive` 父节点首次加载且尚未发生可见性操作时，必须默认且仅显示第一个直接子节点；用户手动隐藏全部直接子节点后必须保持全部隐藏，不得再次回退显示第一个子节点；空容器不显示子节点。切换条始终按内容宽度展开并允许溢出节点边界，不设最大宽度或内部滚动区域。从 `Exclusive` 切回 `Stack` 时必须清除全部直接子节点因互斥选择产生的隐藏状态并立即显示所有子节点，后代节点自身的独立隐藏状态保持不变。切换条仅改变现有子节点可见性状态，不能触发参考图重读、视口重新适配或预览树的异步重建。
+
+`BestFit` 文本测量的 effect 只依赖字号模式的标量值、文本测量键和实际容器，不能依赖整个 `FontSizing` 对象引用。UI State 对任意节点（包括切换 `children_display_mode`）的不可变更新会 clone 整棵树；等值 clone 不得重新创建 `ResizeObserver` 或同步重复二分测量，以避免最终预览已显示时出现明显的“重新加载”。
+
+## 2026-08-19 UI Editor 节点几何唯一 seam
+
+`features/ui-editor/nodeTransformGeometry.ts` 是 UI Editor 节点几何的唯一 seam：它统一解析页面 rect 和节点 context、按 anchor / offset 反算 transform、同树 reparent 意图、父节点变换时的直接子节点页面位置保持，以及预览 resize 的等比约束。页面 Inspector、预览 pointer interaction 与状态迁移分别作为该 Module 的 adapter；它们不得再递归计算节点尺寸、各自反算 offset 或复制子节点保持逻辑。跨界面移动仍只保留原局部 transform，不进入 page rect 换算。
+
+此 seam 的纯测试覆盖嵌套 context、offset 反算、同树重挂载、子节点页面位置保持与 Inspector anchor preset 保位；几何修复应在此 Module 局部验证后由三个 adapter 复用。
+
+左侧 `UI Tree` 与预览画布复用同一个节点右键菜单组件和条目模型，顺序固定为“新增子节点 → 新增同级节点 → 删除节点及子节点”。页面根仅显示“新增子节点”；虚拟超级根不提供菜单。预览仅在“编辑叠加”模式中响应已渲染节点的鼠标右键，右键会选中该节点并阻止嵌套节点事件冒泡；“最终预览”以及画布空白处保留原有行为，空白处不接管浏览器原生菜单。
+
+菜单由页面级 portal 呈现，使用屏幕坐标且在视口边缘内收，避免受预览画布缩放和容器裁切影响。点击菜单外、按 Escape、窗口失焦、滚动或调整窗口大小均关闭菜单。全局 `controller.editor.isLocked` 时，节点仍可选中和查看菜单，但所有结构修改项禁用；状态层的 mutation 校验继续作为最终防线。点击可用项先关闭菜单再执行现有 controller 动作，不改变既有新增或删除后的选择策略。
+
+## 2026-08-19 UI Editor 预览等比角点缩放
+
+UI Editor 预览中按住 Shift 拖动四个角点时，以本次进入等比缩放时相对原尺寸变化更大的轴作为主轴（完全相等时取水平轴），并在本次指针拖动内锁定。主轴按手柄方向和位移符号决定放大或缩小；另一轴只由初始宽高比推导，对角保持固定。不得再从两个轴各自推导的候选尺寸中取较大值，否则一轴放大、另一轴缩小时会覆盖较小轴的输入，导致控制点看似朝鼠标反方向跳动。锁定后，受比例驱动的从轴可以不跟随鼠标在该轴的位移，这是等比约束的明确结果。
+
+## 2026-08-18 UI Editor Inspector 统一锁定态
+
+UI Editor Inspector 的全局只读状态唯一来源是 `controller.editor.isLocked`。`InspectorSidebar` 在根层提供共享只读 Context，并在顶部只显示一次状态徽章：锁定时使用现有 slate 风格与“只读”锁图标，解锁时显示“可编辑”；整个 Inspector 内容区同步使用锁定表面。节点根的 Transform 局部只读继续仅约束该 Transform 区域，不能被解释为整个 Inspector 已锁定。
+
+全局锁定时所有会修改 State 的 Inspector 控件必须禁用或设为只读，包括文本 / 数值输入、选择器、复选框、组件增删改排和 Sprite 九宫格预设、数值、指针导轨编辑。查看、复制以及不产生 State 修改的展开 / 折叠保持可用。所有 mutation 回调还须在入口检查只读状态，不能只依赖禁用样式，避免键盘或程序化事件绕过锁定。Transform 内不再重复显示全局“只读 / 可编辑”徽章。
+
+## 2026-08-18 UI Editor 从属页面、手势与保存失败边界
+
+`UIDesignImage.metadata.slave_to` 是有向无环关系。编辑器状态层拒绝自指、会形成环的赋值以及已损坏或缺失的引用链；Inspector 只将当前图片及其下游后代从可选主页面中隐藏，不能替代状态层校验。UI State 写入前 Rust 持久化校验再次拒绝任意环，保证手工编辑或旧文件同样不能落盘。
+
+预览节点拖拽与缩放共用单一内部手势状态机，每次只能有一个指针操作。状态机保存手势所属界面图、节点、指针和捕获目标；界面图或树切换、指针取消和组件卸载都会释放捕获并清空状态。所有输入和输出几何值必须为有限数，缩放比例还必须大于零；检查失败直接取消操作，不向 State 写入变换。
+
+资源保存的冲突和异常均在编辑器页面持久显示，并可主动关闭；普通异常只显示固定安全摘要，不能显示底层错误正文。保存并返回只在保存成功后关闭返回确认并离开页面；失败后保留确认上下文，以便用户修复、重新加载或重试。
+
+## 2026-08-18 UI Editor 结构识别、合并与增量导入边界
+
+UI Editor 当前把“识别界面结构”定义为结构草稿阶段，而不是完整视觉还原阶段。识别 DTO 只负责输出节点层级、几何、名称、描述和置信度；节点组件暂为空，由后续“绑定视觉素材”阶段补齐 Image / Text 组件。`applyRecognitionResult` 可以整体替换当前 `ui_trees`，但该替换只代表结构结果，不能宣称已经保留截图中的视觉内容；组件状态使用 `NoProblem`，前置检查仍会根据空组件和素材绑定情况阻止跳过绑定阶段。
+
+结构识别、界面语义建议、多图合并和组件绑定只接受不超过 `1 MiB` 的 LLM 工具调用 arguments，并在递归业务类型反序列化前先解析为通用 JSON、迭代检查结构预算。结构识别按每棵返回树独立限制为最多 `512` 个 LLM 节点和 `32` 层，不汇总多棵树的节点数，也不计 Rust 自动补建的页面根；界面语义建议最多 `4` 个节点和 `4` 层；合并计划最多 `512` 个计划节点和 `32` 层，`Simple.children` 与 `Merged.merged_from` 使用同一计数和深度口径；组件绑定 `changes` 不得超过当前可编辑节点数且绝对上限为 `10,000`，每个 change 的完整组件栈最多 `64` 个组件。任何超限结果均整次拒绝，不截断、不返回部分结果，也不把工具 arguments 正文写入日志。
+
+多图合并使用 LLM 返回的语义投影树。`Simple` 和 `Merged` 只列出希望进入结果树的原始节点；未被计划引用的源节点表示本次合并判定为冗余或不属于目标公共结构，允许被丢弃，不要求 `used_original_ids` 覆盖全部输入节点。重复 ID 和未知 ID 仍然是错误；省略不是隐式复制或随机删除，而是合并计划的正式语义。
+
+`merge_ui` 的 Tauri 命令参数继续保持 `State`，不新增前端字符串 payload 或 IPC 参数上限。命令进入 Rust 后、构建 LLM 请求前，按每棵源树独立限制 `512` 个节点和 `32` 层，不跨树求和；序列化投影超过 `2 MiB` 时同样拒绝。本边界不宣称覆盖 Tauri 自身的入参反序列化阶段。
+
+UI Editor 的图片、字体和远程素材导入采用增量提交合同：输入先完成各入口已有的预检，随后按顺序逐项写入和登记；前面已成功的项目在后续写入或登记失败时保持有效，调用方必须重新读取 manifest 取得已提交集合。远程素材目标文件名必须同时包含清洗后的可读 ID 与原始稳定 ID 的确定性摘要，不能让不同 ID 因清洗结果相同而覆盖已有文件；同一批次计算出的重复目标路径必须在写入前拒绝。该入口不提供整批事务回滚，也不承诺失败后“零文件、零 manifest 变化”；后续如需原子批量导入，必须新增明确的 transaction / reconciliation 合同，不能把当前入口静默改成另一种语义。
+
+作为 LLM 视觉输入使用的 UI 设计图和独立素材单张文件上限为 `5 MiB`，不设置多图合计大小上限。前端设计图 AssetImporter 对本地和远端入口使用相同单文件限制；结构识别、界面语义建议与组件绑定在 Rust 中先检查文件元数据、再有限读取，并把读取与 base64 编码放在 blocking worker，避免阻塞 Tokio async worker。本阶段不新增图片像素数限制或命令超时。
+
+## 2026-08-18 UI Editor 左侧节点树跨界面移动
+
+左侧 UI 节点树使用 UI-only 的虚拟超级节点统一承载现有 `ui_trees` 的页面根节点，仅改变树视图，不写入 State 或持久化契约。页面根节点和超级节点不可拖动；普通节点可在不同页面根节点之间拖动，整个子树随节点移动并保留原 `transform`。这里的“保留”只表示复制节点原本的局部布局参数，不承诺跨界面后的页面像素位置稳定：不同界面图拥有独立的画布尺寸、像素密度和父节点坐标空间，跨树坐标换算没有可靠的默认语义，因此本次不做换算，也不把跨树移动后的视觉位置描述为“保持不变”。
+
+同一界面图内的重新挂载沿用原有页面几何语义：先计算节点和目标父节点在页面坐标中的矩形，再换算出目标父节点下的新局部 `transform`，以保持节点在页面中的位置稳定。跨界面移动与同界面重新挂载是两条不同的行为；前者只保留原局部 `transform`，后者才做页面矩形换算。两种移动都不会自动切换当前 active image；后续如需跨界面坐标换算，另行设计。
+
+## 2026-08-17 UI Editor 项目字体导入与预览
+
+UI Editor 的 `State.font_assets` 正式承载项目字体面资源；`FontAsset` 包含项目资产 ID、受控项目相对路径、内容 SHA-256，以及由 Rust 解析的 family、face、weight、italic、格式和源文件名。`TextComponent.font` 直接绑定一个具体字体面，`font_style` 继续表达组件要求的 Normal / Bold / Italic / BoldItalic 浏览器字形；预览将其稳定映射为 CSS `fontWeight` 与 `fontStyle`。UI Editor 整体 State 仍只属于当前桌面会话，不新增持久化合同。
+
+字体资源发现与 Sprite 保持同一项目资产语义：两种 importer 在 FileManager Home 下都从唯一的 `本地项目` 根进入，再按各自 `typeFilter` 展示已登记资源；不扫描或接纳未登记文件，字体不展示云端素材库。从电脑导入使用 Tauri 系统文件选择器，Rust 整批读取普通文件，拒绝符号链接、集合字体、超过 `8 MiB` 的单文件、超过 `64` 个字体面或 `32 MiB` 项目总量，完成真实签名、字体表、名称与 weight/style 解析后复制到 `assets/fonts/` 并登记 manifest。内容相同的字体复用已登记资源；Sprite 与 Font 的 State 批量加入都采用幂等合并：相同 ID 且完整资源相等时跳过，同 ID 数据冲突时整批失败。删除只移除会话 State 资源并清空相应 `Image.target_graphic` 或 `Text.font` 引用，不删除项目文件或 manifest 条目。
+
+候选格式为 TTF、OTF、WOFF 和 WOFF2，但 Rust 安全解析是导入硬门；当前解析依赖不能完整解析的压缩 Web Font 必须拒绝，不能把浏览器可能加载当作验证成功。已登记字体字节只能经字体专用 Tauri 命令读取；命令重新核对 manifest 的 asset ID / 相对路径、普通文件、大小、字体结构与摘要。Importer 预览也只读取同一受 manifest 约束的字体字节，再临时加载 `FontFace` 显示黑色的中英文、数字和标点多字号样张；切换选择或关闭时立即卸载。前端以 `FontAssetId` 派生私有 CSS family，创建 Blob URL 和 `FontFace`，加载成功后加入当前 `document.fonts`，资源变更或卸载时删除 FontFace 并回收 Blob URL。同名 family 不共享浏览器注册名。预览仅在绑定字体已加载时使用其私有 family；加载中、失败或悬空引用均回退系统字体。`BestFit` 使用同样式的不可见浏览器文本节点和容器实际尺寸，在整数 `[min,max]` 中二分取得最大可完整容纳字号；没有字号能完整容纳时使用 `min`，容器、文本、字体族、字形、行高或溢出规则变化后重新测量。WebView 加载失败或字体缺少当前文本字形时不阻塞后续阶段，Inspector 显示非阻断提示并回退系统字体；悬空字体 ID 继续由 prerequisite 阻止。
+
+## 2026-08-18 UI Editor 图片 / 字体通用 AssetImporter 契约
+
+图片和字体共用同一个 `AssetImporter`，组件不再接收 `mode` / `kind`，也不暴露候选项或结果项的 React 渲染回调。调用方只传入 image/font 两份 settings：标题、图标、本地 / 远端来源分支、来源专属 `typeFilter`、系统文件选择器规则、数量 / 大小 requirements 和导入 policy。`typeFilter` 只决定候选是否展示；requirements 在提交前限制数量、单文件大小和总大小；文件管理器、预览、加载态、错误态和导入队列由 importer 内部统一处理。
+
+本地和远端候选项保持来源专属字段，不用可选字段猜测来源。项目树已有登记资源直接交付统一的 `ImportedAsset`；从电脑或云端导入时，importer 调用唯一 Tauri `import_ui_editor_assets` 命令。命令请求是按 `source` 分支的联合结构，分别使用 `localSourcePaths` / `localPolicy` / `localRequirements` 或 `remoteAssets` / `remotePolicy` / `remoteRequirements`。Rust 对目标目录、实际文件签名、媒体类型、扩展名、数量和大小做最终白名单校验；字体只允许本地源，图片允许本地与远端源。旧的三个 UI Editor 导入 command 不再注册为 Tauri command。
+
 ## 2026-08-12 Issue #163：子 Agent 澄清回执中转
 
 正式用户对话 Agent 仍固定为 `project-supervisor`；委派专业 Agent 和隔离 child 不得直接调用 `user.input_request`。当 child 缺少会实质改变结果的用户事实时，child 以短小的 `AGC_NEEDS_USER_INPUT_V1` + 结构化 JSON 终态回执交付问题，Runtime 将其作为 `needs-user-input` delivery，而不是 `needs-repair`。
@@ -999,13 +1069,14 @@ game-project/
 - 根 Supervisor 只对 manifest 中已经 Completed 的 seed task执行正式产物、素材和 Canvas 深验；未完成状态本身已经阻塞根完成，禁止在 code-prototype 尚未开始时提前扫描四类素材。自动唤醒连续耗尽 200 次瞬态预算后进入 `needs-reconciliation`，不得静默保留 running。
 - Canvas 可见性区间证明按 Oxc semantic symbol 与当前绘图 context 的 Canvas owner 解析：函数 alias 重绑定、可达调用参数、计数循环和作用域内数值常量都必须保持身份。无法化简的格子索引只在唯一 `COLS / ROWS / CELL` 合同下覆盖完整棋盘轴；已知越界实参继续拒绝。动态 clamp 只接受未遮蔽全局 `Math.min(currentCanvas.width|height - size, Math.max(0, dynamic))`，错误 Canvas、遮蔽 Math 和普通未知坐标失败关闭。
 - parent wake 达到瞬态预算上限时先形成 durable reconciliation signal；lane 忙保留 deferred 状态，随后在同一 execution lane 与项目写锁内重读原始 state、最新 durable task、取消墓碑和 DAG 进展。manifest 结构损坏时使用不依赖 manifest hydration 的专用 CAS journal 与原子 state 写入，不能吞掉持久化错误，也不能用过期终态覆盖并发取消或 child 进展。durable terminal reconciliation task 是后续 state / queue / event / audit 的提交标记；重启恢复必须在其它 resume 动作前幂等补齐这些投影，task journal 读取损坏不得当作任务不存在。恢复只在 raw state 具有完整 Agent/task/Session/run/source/profile/binding/task 身份时选择其当前 run；state 缺失、JSON 损坏、空对象或 runId 等关键身份为空时只考虑 journal 最后一个 logical run，完整有效的新 Run 继续阻止历史 marker 覆盖。event 与 Agent DB audit 只有完整稳定 payload 唯一匹配时才视为已投影，同键冲突或重复必须失败关闭；旧 task 已 completed/cancelled、Runtime 已离开 waiting 或新 Run 已接管时，deferred signal 必须追加 run-scoped resolved/superseded 终局。
+
 ## 2026-08-04 manifest 与工作台一致性收口
 
 - `.agent/manifest.json` 的存储写边界使用同目录持久文件锁跨线程、跨进程串行化；锁必须覆盖旧 manifest 读取、不可变版本前缀校验、临时文件安装和安装后回读一致性校验。锁文件拒绝符号链接、非普通文件和异常所有权 / 硬链接；Windows 使用不共享写句柄，Unix 使用 `O_NOFOLLOW + flock`。旧快照在新版本安装后只能被拒绝，不能覆盖已追加版本。
 - 后台 Agent 的 manifest 变化以共用 Runtime 状态投影 / 终态 emitter 作为失效因果点：`game-creator-agent-runtime-update` 的 Rust / TypeScript DTO 固定携带 `manifestInvalidated`，且 App 必须在 Supervisor、selected agent、session 和 run 身份的任何 early return 之前处理失效。GUI 进程内 Runtime 直接发该事件；External Runner 是独立进程、没有 GUI `AppHandle`，因此 Runner 协议 v5 的 `runner.attach_gui_owner` 必须登记 GUI 创建的随机 loopback 端口和 64 位随机令牌，Runner 的同一 emitter 通过受令牌保护的短连接转发 `game-creator-manifest-invalidated`。两条路径都只传项目路径与 Agent 身份，不复制 manifest，也不靠轮询补偿。
 - App 收到当前项目的 Runtime / relay 失效后重新调用 `get_local_game_manifest`。重读按项目 single-flight 合并事件风暴；读取中再到达失效只追加一轮串行重读，不并发提交同项目响应。应用结果同时校验组件仍挂载、当前项目路径和项目 scope version；项目切换、组件卸载或旧 scope 的迟到响应不得覆盖新项目。Project Supervisor 对外发布前以“revision 前读 -> manifest -> revision 后读”取得一致快照，再通过 `onManifestChange(projectPath, manifest, metadata)` 携带 `projectId + revision + source`；启动器按 `projectPath + projectId` 只接受更高 revision，同 revision 只接受内容一致的重复，旧轮询和同 revision 分叉都不得覆盖。资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。集成测试记录“事件未重新打开项目”的调用基线前，必须先等待项目写入最近列表后触发的只读目录状态刷新完成，不能把这项合法后台检查误算成失效事件副作用。
 - `.agent/agent.db` 有界尾部读取报告截断时，审计 producer 映射失败关闭，不生成基于不完整审计的 producer、task flow 或对应任务环。前端收到截断 DTO 时只剔除 `producerAssignments`、`taskFlows` 与对应 `cyclicTaskIds`；Rust 根据当前 manifest、精确资源引用和仍可信任务深度下限返回的 `dependencyDepths` 继续保留，前端只校验资源仍存在且深度为非负安全整数，不得自行重算或压平权威深度。精确引用边、reference connection index、`cyclicResourceIds` 与 unresolved references 同样继续保留。
--- 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦按稳定 `resourceId` 驱动焦点状态：仅 `null -> id` 或 `idA -> idB` 聚焦详情 region，同一 ID 的 manifest 重投影不得抢走音频、视频、链接或关闭按钮焦点；显式收起和 Escape 恢复画布滚动并优先聚焦原触发卡片。聚焦资源被删除时清理 stale focused / selected ID，关闭详情并把焦点落到资源搜索框；项目切换或运行视图切换清除旧恢复意图，不得恢复旧项目卡片。橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。
+  -- 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦按稳定 `resourceId` 驱动焦点状态：仅 `null -> id` 或 `idA -> idB` 聚焦详情 region，同一 ID 的 manifest 重投影不得抢走音频、视频、链接或关闭按钮焦点；显式收起和 Escape 恢复画布滚动并优先聚焦原触发卡片。聚焦资源被删除时清理 stale focused / selected ID，关闭详情并把焦点落到资源搜索框；项目切换或运行视图切换清除旧恢复意图，不得恢复旧项目卡片。橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。
 
 ## 2026-08-05 客户端素材创作无限画布阶段一合同
 
@@ -1073,7 +1144,7 @@ game-project/
 - 资源编辑账本把远端明确失败固化为 `remote-failed`，只保存稳定失败分类和终态时间；该状态不得再 POST 或轮询，只能由用户显式置为 `archived` 后移出活动恢复队列。归档不删账本、不伪装 `committed`；`result-unknown` 和 `reconciliation-required` 不允许归档或换键重试。
 - 派生资产提交使用 `game-creator-resource-edit-asset-transaction.v1` durable journal，绑定 operation/project/source、最终路径和媒体摘要、manifest before/after 及 base/target project revision，阶段固定为 `prepared -> media-installed -> manifest-written -> revision-written -> committed`。重启后只对可证明组合前向补齐；manifest 已 after 但 revision 仍为 base 时只补目标 revision，身份、摘要、重复 asset 或 revision 任一冲突则进入 `reconciliation-required`。ledger 只能在文件、manifest、revision 与 journal 全部回读一致后进入 `committed`。`committed` 后若仍有 staging，只有在 staging 与 journal 摘要一致、正式媒体摘要一致，且 manifest 按 asset ID 或路径只能找到唯一一条并与 journal asset 精确相等时才尽力清理；删除 staging 的 I/O 失败不改变 durable committed 结果，任何身份或媒体漂移都保留 staging，并把 journal 与 ledger 转入对账。
 - 派生子版本 journal 同时冻结 project revision before/after 的完整身份与目标 after 记录。manifest 已存在目标子版本但 journal 缺失时不得据此补造提交证明；升级前 journal 缺少 revision 身份时，只有当前 revision 仍精确处于 base 才能补齐 before/after 身份，已经推进且无法证明由本事务写入时必须失败关闭并进入 `reconciliation-required`。
-- 工作台顶部恢复入口只打开独立 modal，不在当前面板下追加列表。面板展示后端权威队列的全部 operation：可继续项可独立恢复，`remote-failed` 只能移出活动队列，`reconciliation-required` 只读展示对账。读取失败保留错误并允许重试，任一操作后重读权威队列；项目切换后的迟到结果必须丢弃。modal 支持 Escape、初始焦点和关闭后焦点归还，窄屏操作按钮改为纵向全宽布局。
+- 工作台顶部恢复入口只打开独立 modal，不在当前面板下追加列表。面板展示后端权威队列的全部 operation：可继续项可独立恢复，`remote-failed` 只能移出活动队列，`reconciliation-required` 只读展示对账。读取失败保留错误并允许重试，任一操作后重读权威队列；项目切换后的迟到结果必须丢弃。通用 `ThemedModal` 使用焦点陷阱：打开时移入 dialog，Tab / Shift+Tab 不得逸出；Escape 或背景关闭后归还原触发元素，无可聚焦子项时聚焦 dialog 本身。窄屏操作按钮改为纵向全宽布局。
 - 草稿应用统一经过单调 revision 门禁：generation progress、保存队列、生成/提交回包与延迟 `loadDraft` 只能推进当前 scope 的最高可信 revision；同 revision 只允许完整相等的幂等回包，低 revision 和旧 scope 一律丢弃。Tauri 指针与键盘 Shift 选择统一调用共享 `resolveLayerPointerSelection`；移动、缩放和背景平移只在首次真实变化时 capture 一次 history，零位移不增加 undo、documentVersion 或草稿保存。
 - `canvas.failed` 必须带 `generation / draft-save / asset-commit / recovery / cancellation` 五类稳定 operation。只有 `generation` 失败允许“返回修改/重新确认”；草稿保存或 CAS 冲突只提供重试保存/重新加载，资产提交和恢复只提供安全恢复/对账，取消故障只允许保留草稿继续编辑。初始恢复读取失败也归 `recovery`，不得显示生成重试动作。
 
@@ -1102,6 +1173,27 @@ game-project/
 - Acceptance Graph 节点由 Supervisor 针对当前任务动态生成，不来自玩法模板。节点记录 required/optional、依赖、状态、证据引用与摘要；只有同一可信根 Supervisor 能调用 `agent.acceptance_update`，且该动作必须独占一轮。failed 与 not-observed 节点形成下一轮定向返工集合，未提交的 passed 节点保持不变。
 - 完成门在普通收束、finalization 和 prepared 恢复中统一消费 Acceptance Graph。任一 required 节点为 failed、not-observed 或缺失都会阻止最终回复；工具成功、计划 completed、文件存在、smoke 或 preview 单独通过均不代表用户目标完成。项目 revision 改变后，整张图先进入待 Supervisor 确认状态；Supervisor 只更新它判断为受影响的节点并确认 current revision，未提交的 passed 节点及其证据保持不变。requiredEvidence 必须命中 Runtime 明确允许的持久证据工具集合，拼错、控制面、纯协调工具和依赖动态 catalog 的 MCP 调用不能形成不可完成合同。动作回执记录执行边界的 `projectRevisionBefore / projectRevisionAfter`：非 mutation evidence 的 before、after 都必须等于验收时 current revision；mutation evidence 的 after 必须等于 current revision。旧 revision、跨 revision 只读结果或执行后延迟落账的回执都不能重放为 passed。
 
+## 2026-08-17 UI Editor 项目资源 State 持久化
+
+- UI 编辑器复用现有 manifest `kind: "UI"`、`mediaType: "application/json"` 资源，不增加平行 asset kind。资源文件固定为严格 `game-creator-ui-design-state.v1` JSON envelope：`projectId`、`assetId`、每资源 `revision` 和 Rust 唯一源 `State`；旧空对象、未知字段、身份错配、超限、无效内部引用和不安全相对路径均失败关闭。内部引用校验同时覆盖 `Image.target_graphic -> sprite_assets` 与 `Text.font -> font_assets`，可选引用非空时必须命中同一 State 内已登记资源。
+- Tauri 专用 load/save command 只接受项目路径、期望项目 ID、manifest asset ID 和（保存时）资源 revision；Rust 按 manifest 解析受控本地路径并在项目写锁内做 CAS。相同 `State` 返回 unchanged 且不推进 project revision；不同内容安装并回读一致后才推进 revision，后续推进失败返回 `reconciliation-required`，不伪装为完整保存。
+- UI State 原子安装保留最近一个可解析、canonical 的 `.previous` 恢复候选，作为最佳努力恢复来源；写入主文件前不把完整 State 语义校验重复执行一遍。主文件损坏时，恢复候选仍必须通过同一严格 schema、project/asset identity、revision、引用和 State 校验后才能安装；恢复安装与保存共用项目写锁，并在持锁后重新读取主文件，已有并发保存的有效新版本时直接返回而不安装旧副本。任一候选均不可信则停在加载错误，前端禁编辑和保存。新建 UI 资源先登记并安装合法 envelope，任一步失败补偿 manifest/文件，避免把空 JSON 留给资源卡。
+- 图片路径只需是安全项目相对路径，不要求外部图片仍存在或已登记为 manifest asset；缺失媒体只导致 preview 占位。`imageOrder`、当前选择、缩放、面板开关和 preview URL 不写入 State，加载后由 State 派生。保存冻结提交快照，保存期间的新编辑继续保持 dirty；AI state lock 和加载期间禁保存。
+
+## 2026-08-20 UI Editor 本地图片预览作用域处置
+
+- UI Editor 每次成功加载 State 后为当前本地图片预览批次创建独立 `scopeId`。切换项目、切换 UI 资源或卸载时，清理逻辑必须先失效前端 ownership fence，再调用 `cancel_local_project_resource_preview_scope` 取消该批次已排队或在途的原生读取；加载完成前尚未创建 scope 时不得发出空取消。旧 scope 的迟到结果不得更新当前 preview URL，回归测试同时覆盖资源切换与卸载。
+
+## 2026-08-18 UI Editor 新建节点组件状态
+
+- 所有非组件绑定流程创建的 UI Editor 节点，`components_status` 与 `layout_status` 一致初始化为 `NoProblem`，覆盖前端新建页面根 / 人工节点，以及 Rust 结构识别与合并产生的节点。组件绑定命令仍只对 LLM 显式返回的节点写入其 `NoProblem` 或 `NeedReview` 结果；未返回的节点状态不变。
+
+## 2026-08-18 UI Editor 节点预览可见性
+
+- 节点显示 / 隐藏是编辑器页面级临时状态，不新增 Rust `Node` 字段，不进入 UI State 保存快照、运行时数据或后端契约。`NodeId` 在 State 内全局唯一，隐藏状态直接使用页面会话级 `Set<NodeId>`；切换界面图保留，跨界面移动随节点保留，清空、重新加载、删除节点或删除界面图时清理失效 ID。
+- 同一可见性状态同时作用于 `编辑叠加` 和 `最终预览`。隐藏节点会截断整个子树，移除节点组件、编辑边框、名称、缩放控制点和画布命中区域；参考图和预览画布本身保持存在。父节点恢复时，子节点此前独立设置的隐藏状态保持不变，根节点不享受特殊限制，也允许隐藏。
+- UI Tree 行提供 `Eye` / `EyeOff` 按钮，按钮只切换状态、不改变选择；节点 Inspector 提供“在预览中显示”复选框，两者共享页面控制器状态。隐藏节点仍可通过 UI Tree 选择并在 Inspector 中编辑，但不会重新出现在画布上，直到恢复显示。
+
 ## 2026-08-13 普通 Web 工作台无人值守生成可靠性收口
 
 - **入口覆盖**：本节取代本文更早“普通 GUI autonomous 继续固定完整 DAG”的现行含义。项目首页进入的普通 Web 工作台必须显式使用 `single-supervisor` 编排，提交映射为 `project-supervisor-game-chat + autonomous-game-build`；持久化 Supervisor 决策前零 child，决策后只启动唯一 `code-prototype` 主 Run，美术仅在该 Run 完成 `asset.list` 并形成可证实缺口后一次委派一个受限 child。独立 game-chat 入口沿用相同规则。显式 `professional-dag` 与 CLI 专业 autonomous 验收继续使用 `project-supervisor-gui|cli + autonomous-game-build` 的原有完整 DAG；Supervisor 调试与 Godot 继续 `project-supervisor-gui + standard`，不得被普通入口默认值误改。

docs/technical/【技术方案】UI编辑器Godot容器布局模型-2026-08-18.md

@@ -0,0 +1,41 @@
+# UI 编辑器 Godot 容器布局模型
+
+更新时间：`2026-08-18`
+
+## 范围
+
+UI 编辑器节点统一采用 Godot 4.x `Control` 风格布局数据。Rust 负责持久化和参数校验；UI Editor 前端将该数据单向生成 Preview CSS。CSS 只是预览后端，不是领域模型，也不需要与 Godot 项目或运行时对接。
+
+本次是破坏性 UI 设计 schema 变更：旧 `Node.transform` 改为 `Node.layout.transform`，不提供迁移。
+
+## 数据模型
+
+每个 `Node` 保留：
+
+```text
+layout: {
+  transform,                    // anchors + offsets
+  custom_minimum_size: [x, y],
+  size_flags_horizontal: 0|1|2|3|4|8,
+  size_flags_vertical: 0|1|2|3|4|8,
+  size_flags_stretch_ratio,
+  container: None | HBox | VBox | Grid | Margin | Center
+}
+```
+
+flags 使用 Godot 数值：`ShrinkBegin=0`、`Fill=1`、`Expand=2`、`ExpandFill=3`、`ShrinkCenter=4`、`ShrinkEnd=8`。默认最小尺寸为 `[0, 0]`，flags 为 `Fill`，stretch ratio 为 `1`。
+
+Container 专属数据是互斥 tagged union：HBox/VBox 存 `alignment + separation`，Grid 存 `columns + h_separation + v_separation`，Margin 存四边 margin，Center 存 `use_top_left`。
+
+## 语义
+
+- 普通 Control：children 继续按自己的 Transform 绝对定位。
+- 父为 Container：父忽略 direct child 的 Transform，使用 child minimum size、flags 与 stretch ratio；Transform 不删除，离开 Container 后继续可用。
+- `children_display_mode` 仍是独立的 Stack/Exclusive 可见性规则；不可见 child 不参与 Container。
+- 不支持 Flex/Flow wrap；Grid 按行优先排列。
+- Margin 的 children 填满内侧矩形；Center 的 children 居中并可重叠。
+- v1 minimum size 只使用 `custom_minimum_size`。TODO：为文本、图片等组件提供 minimum-size，再与 custom minimum 逐轴取最大值。
+
+## 编辑器交互
+
+布局只在 Inspector 编辑。Preview 不为 Container 管理的 child 提供拖拽或缩放手柄；Inspector 会提示其 Transform 被父 Container 忽略。普通 Control 仍保留原 Transform 编辑和自由预览操作。

docs/technical/【技术方案】UI编辑器子节点显示规则-2026-08-18.md

@@ -0,0 +1,26 @@
+# UI 编辑器子节点显示规则
+
+## 规则
+
+`Node.children_display_mode` 控制父节点直接 children 的预览显示方式：
+
+- `Stack`：所有直接 children 按现有树结构显示。
+- `Exclusive`：直接 children 中允许显示 0 或 1 个。
+
+`Merged` 合并容器由 Rust materialize 阶段直接设置为 `Exclusive`，不由 LLM 决定，也不需要历史数据迁移。
+
+## 状态与交互
+
+编辑器预览可见性仍是按界面图隔离的临时状态。Tree Panel 的节点眼睛操作和最终预览的互斥 tab bar 必须共用同一套可见性状态：
+
+```text
+[子节点 A] [子节点 B] [子节点 C]
+```
+
+当前可见 child 高亮；点击其它 child 会隐藏兄弟并显示目标；点击当前高亮 child 会将其隐藏，允许进入全部隐藏状态。没有 child 可见时不高亮任何 tab。
+
+最终预览只在当前选中的父节点为 `Exclusive` 时显示 tab bar。Inspector 只提供“子节点显示模式：叠加 / 互斥”选择，不增加独立的当前状态或隐藏按钮。
+
+## 默认行为
+
+`Exclusive` 节点没有显式隐藏状态时，最终预览按 children 顺序显示第一个 child。首次通过 Tree Panel 或 tab bar 修改后，状态由共享可见性状态明确记录。