Merge remote-tracking branch 'origin/master' into fix/ui-editor-enexpected-select

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

@@ -15,6 +15,8 @@
 
 预览树在会话边界归一化为 `UITree | null`：尚未选择界面图、正在加载或尚未识别树时均以 `null` 表示，不能把 `Array.find` 的 `undefined` 传播到视图接口。
 
+素材缩略图的加载失败状态按“素材 ID + 预览 URL”记录；同一 URL 失败后显示占位图，资源重新加载或重新导入产生新 URL 时必须允许再次尝试，不能把失败永久绑定到素材 ID。
+
 保存与代码生成共享同一份持久化 State/revision。会话层在保存或生成进行期间互斥拦截，且代码生成必须基于已加载的持久化 revision；视图层的保存按钮和“保存并返回”按钮同步遵守该互斥状态。
 
 `UiDesignStateStore` 的 `generateCode(assetId)` 是必需能力，返回成功结果时不得为 nullable；所有注入的 adapter 与测试替身都必须实现该方法。

docs/technical/【前端设计】UI编辑器图片素材选择器-2026-09-03.md

@@ -0,0 +1,41 @@
+# UI 编辑器图片素材选择器
+
+> 更新时间：`2026-09-03`
+
+## 目标
+
+在 UI 编辑器 Inspector 的图片组件中，用独立 modal 图片选择器替换原生素材下拉框，使用户绑定素材时可以看到现有预览图或缩略图。
+
+## 数据来源与边界
+
+- 素材列表继续使用 Inspector 当前的 `sprites`，顺序沿用 `Object.entries(sprites)`。
+- `SpriteAsset` 不新增缩略图字段。预览继续消费 UI 编辑会话已有的 `previewUrls: Record<string, string>`；预览缺失不影响素材绑定。
+- `previewUrls` 由 Inspector projection 沿 `NodeInspector → ComponentPanel → ImagePanel` 传入选择器。
+- 本次不新增后端接口、持久化字段、搜索筛选或二级大图预览。
+
+## 交互合同
+
+### Inspector 触发区域
+
+- 正常绑定显示素材名称。
+- 空值显示 `未绑定`。
+- 引用不存在的素材显示 `素材不存在（<ID>）`，保留原 ID，不在打开面板时自动清除。
+- 未绑定时按钮文案为 `选择素材`；已有绑定或失效引用时为 `更换素材`。
+- `readOnly` 时按钮禁用，不能打开选择器。
+
+### 素材选择 modal
+
+- 使用现有 `ThemedModal`，带遮罩、关闭按钮、Esc 关闭和点击遮罩关闭。
+- modal 内容使用纵向 flex；素材区域占据剩余空间并内部滚动，modal 设置最大高度。
+- 素材以弹性网格展示，卡片包含预览图和素材名称，图片使用 `object-contain`。
+- 有预览时显示 `previewUrls[id]`；无预览或加载失败时显示棋盘格背景与 `ImageIcon` 占位，素材仍可选。
+- 当前绑定项显示选中边框或标记。
+- 第一项为明确的“清除选择”，点击立即写入 `null` 并关闭。
+- 点击任意正常素材立即写入其 ID 并关闭；重复点击当前素材也按相同流程处理。
+- 当前失效引用保留为禁用信息卡，显示 ID；用户仍可使用“清除选择”。
+- 素材为空时显示 `暂无可用素材`，保留关闭操作。
+- 卡片支持 Tab 聚焦以及 Enter/Space 选择；关闭后焦点返回触发按钮。
+
+## 验收
+
+自动化测试覆盖：打开/关闭、按钮和名称状态、当前项高亮、选择 ID、清除 `null`、缺预览占位、失效引用、空列表、`readOnly` 禁止打开、键盘选择和遮罩关闭。实现后运行定向测试、前端类型检查、编码检查及 `git diff --check`。