Merge branch 'master' into feat/canvas-undo-protection

docs/project-memory/shared-memory/pitfalls.md

@@ -22,12 +22,12 @@
 - 验证：覆盖 nanobanana2 / gpt-image-2 的比例与 K 档尺寸矩阵、VectorEngine 最终请求体、普通图片 / 角色 / 图标 / UI 占位，以及低分辨率去背景结果只贡献 alpha、不贡献被放大的 RGB。
 - 关联：`src/components/image-editor/ImageCanvasGenerationModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/platform-image/src/vector_engine/request.rs`。
 
-## 多产物任务保留中间原图不等于把中间原图放进画布
+## 多产物任务的中间原图不能只落资源库
 
-- 现象：角色形象只提交一次、任务列表和泥点也只记录一次，但画布同时出现透明角色与纯色背景角色；图标或 UI 生成也可能多出一张纯色背景图集。
-- 原因：后端为了可追溯和后处理失败恢复而持久化 provider 原图时，又把它与透明主结果一起传入同一次 `canvasCompletion`，把“资源必须保留”错误等同为“画布必须展示”。
-- 处理：provider 原图继续写 OSS、项目资源和账号素材库；正常成功的画布只放透明主结果及明确需要的图标 / UI 拆分素材。仅当透明处理最终失败时，才用 provider 原图作为唯一主图完成占位。
-- 验证：覆盖角色正常成功只落一个图层、图标 / UI 正常成功不落 provider 原图、无切片时只有透明主图集，以及透明处理失败仍由原图单独完成占位。
+- 现象：角色形象、图标 spritesheet 或 UI 素材提取正常成功后，画布只有透明结果，用户无法直接对照和复用 provider 原图。
+- 原因：后端虽然为追溯和后处理失败恢复持久化了 provider 原图，但完成画布只写入透明主结果和拆分素材，把“资源已保存”错误等同为“用户已拿到原图”。
+- 处理：provider 原图始终写入 OSS、项目资源和账号素材库；三类任务正常成功时都同时落透明主结果与右侧 provider 原图，生成器 `generatedLayerId` 仍指向透明主结果，图标 / UI 拆分素材从原图右侧继续排列。仅当透明处理最终失败时，才用 provider 原图作为唯一主图完成占位。
+- 验证：覆盖三类任务正常成功都落透明结果与原图、原图位于透明图右侧、`generatedLayerId` 指向透明图、图标 / UI 拆分素材位于原图右侧，以及透明处理失败仍由原图单独完成占位。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
 
 ## phase 上报的业务拒绝与传输失败不能共用字符串错误
@@ -130,8 +130,8 @@
 ## 画板参考图 objectKey 必须先做归属校验
 
 - 现象：画板生成、快速编辑、图标素材或 UI 素材提取如果允许直接提交 generated objectKey，用户只要知道其他账号的私有 objectKey，就可能让 api-server 签名读取并送给外部生成供应商。
-- 原因：Data URL 参考图可以直接解析，但 objectKey 是服务端私有对象引用；只校验 generated 前缀、mime 和大小不能证明它属于当前账号。
-- 处理：所有编辑器参考图入口统一走 `parse_editor_reference_image(state, owner_user_id, source)`；objectKey 分支必须先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key，再读取 OSS。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
+- 原因：Data URL/Blob URL 只允许停留在浏览器临时态，正式编辑器引用必须先上传并经统一 resolver 校验归属。
+- 处理：所有私有对象引用在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口（生成 / 重绘 / 图标 / UI 提取等交给 provider 的路径）再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
 - 验证：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_reference`，并用前端 workflow 测试覆盖 `referenceImageSrcs` 进入图标生成请求；若快速编辑重开额外参考图，再补对应请求覆盖。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-client/src/assets.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`。
 
@@ -3189,3 +3189,11 @@
 - 处理：在调用 `try_with_tx` 前通过 `let caller = ctx.sender()` 捕获真实调用者，再把 `caller` 显式传入事务函数；迁移、后台账号、runtime profile、外部生成等现有 procedure 已采用这一模式。`npm run check:spacetime-runtime-access` 禁止编辑器 runtime writer 鉴权重新直接读取事务 `ctx.sender()`。运行环境升级到 2.6.1 后继续保留显式 caller，避免鉴权依赖 SDK 版本细节。
 - 验证：运行 `npm run check:spacetime-runtime-access`、`cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`；发布使用 SpacetimeDB 2.6.1 构建的新模块后，以 runtime writer identity 重试 `POST /api/editor/icon-spritesheets/slices`，确认来源查询、分片素材写入与 cohort 完成不再返回 identity 403。
 - 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`scripts/check-spacetime-runtime-access.mjs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## Portal 弹窗必须在遮罩根节点携带平台主题
+
+- 现象：项目库点击“重命名”后，标题、输入框和按钮仍显示，但弹窗面板及遮罩背景变透明，看起来像“改名界面的背景没了”。
+- 原因：`UnifiedModal` 默认 portal 到 `document.body`；若业务入口只在页面内层继承 `platform-theme`，portal 根节点不会继承该容器的 CSS 变量。此时 `.platform-modal-shell` 的 `background: var(--platform-modal-fill)` 和 `.platform-overlay` 的背景声明都会失效。
+- 处理：平台白底工具弹窗优先复用 `PlatformToolModalShell`，由共享壳读取当前 `AuthUiContext.platformTheme`，并把 `platform-theme platform-theme--<light|dark>` 挂到 portal overlay；不要用硬编码白底掩盖主题变量缺失。必须直接使用 `UnifiedModal` 的特殊场景，也要在 `overlayClassName` 显式传递当前平台主题。
+- 验证：在 light / dark 主题下打开 portal 弹窗，断言 dialog 的 overlay 携带对应主题类，并在真实浏览器核对 panel 与遮罩的 computed background 均非透明。
+- 关联：`src/components/project/ProjectGalleryView.tsx`、`src/components/common/PlatformToolModalShell.tsx`、`src/components/common/UnifiedModal.tsx`。